Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ The format of this changelog is based on

## Unreleased

### Added

- `render!` warns about each keyword argument it doesn't recognize, which it would otherwise
ignore silently, once per session and once per `Schematic` render. `OptionalStyle` flags are recognized automatically, and
`DeviceLayout.register_render_kwarg!` registers other custom rendering options.

### Fixed

- `halo` of a path style with zero extent at its start covers the rest of the style, and
Expand Down
2 changes: 2 additions & 0 deletions docs/src/concepts/render.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ The behavior of [`render!`](@ref) can be customized with keyword arguments. Many

Additional rendering options can be provided for user-defined [conditional rendering](#Conditional-Rendering).

When rendering to a `Cell` or `SolidModel`, `render!` warns about a keyword argument it doesn't recognize, since a misspelled option would otherwise be ignored. Flags of `OptionalStyle`s are recognized automatically; register other custom options with [`DeviceLayout.register_render_kwarg!`](@ref).

## Targets

Rendering options and the `map_meta` function can also be provided using a `Target` instead of keywords: `render!(cell, coordsys, target)`. This is especially useful in schematic-driven design, where various `Target`s can be specified as part of your [PDK](./pdks.md), allowing you to target different process technologies or simulation backends given a single design. (The name "Target" is meant to evoke "compilation target".)
Expand Down
7 changes: 5 additions & 2 deletions docs/src/developers/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,12 @@ otherwise. Throw an error rather than guess at what the user intended
until changed.
- The `uniquename` counter, the `Memoization` cache for B-spline tangent optimization, and the
PolyText font caches are process-global.
- `render_kwargs.jl` keeps the set of keyword arguments `render!` recognizes, to which each
`OptionalStyle` adds its flag, and the set of unknown keyword arguments `render!` has
already warned about.
- Some warnings are shown once per session: deprecation warnings with `maxlog=1` (see
[Deprecations](@ref dev-deprecations)), and `recover_curves` warns once per entity type
about lost curves. Test items share a process, so a test asserting such a warning
[Deprecations](@ref dev-deprecations)), `recover_curves` warns once per entity type
about lost curves, and `render!` warns once about each unknown keyword argument (until the next `Schematic` render). Test items share a process, so a test asserting such a warning
depends on nothing earlier having triggered it.

## Style
Expand Down
1 change: 1 addition & 0 deletions docs/src/reference/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,7 @@ See [Shapes](./shapes.md).

```@docs
render!
DeviceLayout.register_render_kwarg!
DeviceLayout.discretize_curve
```

Expand Down
3 changes: 3 additions & 0 deletions src/DeviceLayout.jl
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,9 @@ export GeometryEntity,
export transform,
translate, rotate, rotate90, magnify, reflect_across_xaxis, reflect_across_line

# Before styles.jl: the `OptionalStyle` constructor registers its flag
include("render_kwargs.jl")

# Entity styles
include("styles.jl")
export OptionalStyle,
Expand Down
1 change: 1 addition & 0 deletions src/precompile.jl
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ else
end
# Reset any DeviceLayout-owned globals touched by workload
reset_uniquename!()
reset_render_kwarg_warnings!()
# Don't bake stale Clipper handles into the package image
global _clip = nothing
end
Expand Down
5 changes: 4 additions & 1 deletion src/render/render.jl
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ function render!(
meta::GDSMeta=GDSMeta();
kwargs...
) where {S}
warn_unknown_render_kwargs(kwargs)
render!.(cell, to_polygons(obj; kwargs...), meta; kwargs...)
return cell
end
Expand Down Expand Up @@ -104,6 +105,7 @@ function _render!(
map_meta=default_meta_map,
kwargs...
) where {S}
warn_unknown_render_kwargs(kwargs)
stack = Vector{Tuple{Cell, GeometryReference}}()
_render_elements!(cell, cs; map_meta=map_meta, memoized_cells=memoized_cells, kwargs...)

Expand Down Expand Up @@ -222,6 +224,7 @@ Rendering a `GeometryStructure` to a `Cell` uses the optional keyword arguments
its reference hierarchy) to render as `prerendered_cell`.

Additional keyword arguments are passed to [`to_polygons`](@ref) for each entity and may be used for
certain entity types to control how they are converted to polygons.
certain entity types to control how they are converted to polygons. A keyword argument that is
not a known rendering option gives a warning; see [`DeviceLayout.register_render_kwarg!`](@ref).
"""
render!(c::Cell, s::GeometryStructure; kwargs...) = _render!(c, s; kwargs...)
82 changes: 82 additions & 0 deletions src/render_kwargs.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Keywords declared by the method that runs the check never reach it, so they need no entry.
# The names are not specific to the destination, so a built-in flag passed to a target that
# ignores it does not warn.
mutable struct _RenderKwargNames
# Each set is replaced rather than mutated, so `render!` reads them without the lock
@atomic known::Set{Symbol}
# Not `maxlog`: the file sink of a schematic's log ignores it, and the check runs per entity
@atomic warned::Set{Symbol}
end
const _RENDER_KWARG_NAMES = _RenderKwargNames(
Set{Symbol}([
# Entity conversion (`to_polygons`, `SolidModels.to_primitives`)
:atol,
:rtol,
:Δθ,
:rounded,
# Forwarded to each entity when rendering to a `Cell`
:map_meta,
:memoized_cells,
# Flags of the built-in `OptionalStyle`s, set by targets
:simulation,
:artwork,
:solidmodel
]),
Set{Symbol}()
)
# `OptionalStyle`s register their flags, and geometry may be built on several threads
const _RENDER_KWARGS_LOCK = ReentrantLock()

"""
DeviceLayout.register_render_kwarg!(s::Symbol)

Declare `s` a valid keyword argument for `render!`, so that passing it does not warn.

`render!` warns about each keyword argument it does not recognize, once per session and once
per render of a `Schematic`.
Constructing an [`OptionalStyle`](@ref) registers its flag automatically. Call this for a
custom option read some other way, for example by a `to_polygons` method for your own style.

A package that constructs an `OptionalStyle` at top level should call this for the flag in
its `__init__`, because registrations made while precompiling are not kept.
"""
function register_render_kwarg!(s::Symbol)
s in (@atomic _RENDER_KWARG_NAMES.known) && return nothing
@lock _RENDER_KWARGS_LOCK begin
known = @atomic _RENDER_KWARG_NAMES.known
@atomic _RENDER_KWARG_NAMES.known = push!(copy(known), s)
end
return nothing
end

function warn_unknown_render_kwargs(kwargs, caller=:render!)
_all_known_or_warned(kwargs) && return nothing
unknown = @lock _RENDER_KWARGS_LOCK begin
warned = @atomic _RENDER_KWARG_NAMES.warned
new = setdiff(keys(kwargs), @atomic(_RENDER_KWARG_NAMES.known), warned)
isempty(new) || @atomic _RENDER_KWARG_NAMES.warned = union(warned, new)
new
end
for k in unknown
@warn "`$caller` does not recognize the keyword argument `$k`, which may have no effect. Check the spelling, or register a custom rendering option with `DeviceLayout.register_render_kwarg!(:$k)`."
end
return nothing
end

# Called by each `Schematic` render, so that every schematic's log and `strict=:warn` see the
# warning
function reset_render_kwarg_warnings!()
@lock _RENDER_KWARGS_LOCK begin
@atomic _RENDER_KWARG_NAMES.warned = Set{Symbol}()
end
return nothing
end

function _all_known_or_warned(kwargs)
known = @atomic _RENDER_KWARG_NAMES.known
warned = @atomic _RENDER_KWARG_NAMES.warned
for k in keys(kwargs)
(k in known || k in warned) || return false
end
return true
end
1 change: 1 addition & 0 deletions src/schematics/schematics.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1709,6 +1709,7 @@ function render!(
sch.checked[] || error(
"Cannot render an unchecked Schematic. Run check!(sch::Schematic), or override by setting sch.checked[] = true (not recommended!)"
)
DeviceLayout.reset_render_kwarg_warnings!()
reopen_logfile(sch, :render)
try
with_logger(sch.logger) do
Expand Down
4 changes: 3 additions & 1 deletion src/schematics/solidmodels.jl
Original file line number Diff line number Diff line change
Expand Up @@ -463,6 +463,7 @@ function render!(sm::SolidModel, sch::Schematic, target::Target; strict=:error,
sch.checked[] || error(
"cannot render an unchecked Schematic. Run check!(sch::Schematic), or override by setting sch.checked[] = true (not recommended!)"
)
DeviceLayout.reset_render_kwarg_warnings!()
reopen_logfile(sch, :render_solidmodel)
try
with_logger(sch.logger) do
Expand Down Expand Up @@ -704,6 +705,7 @@ function SolidModels.render_conformal!(
sch.checked[] || error(
"cannot render an unchecked Schematic. Run check!(sch::Schematic), or override by setting sch.checked[] = true (not recommended!)"
)
DeviceLayout.reset_render_kwarg_warnings!()
reopen_logfile(sch, :render_solidmodel)
try
with_logger(sch.logger) do
Expand Down Expand Up @@ -808,7 +810,7 @@ function _render_conformal!(sm, sch, target; context, kwargs...)
)
# That render samples mesh sizes from the formed regions, which carry no `MeshSized`
# styles, so sample them again from the original elements, as `render!` does
SolidModels.populate_size_fields!(
SolidModels.populate_size_fields_unchecked!(
mapped;
primitives_of=(el; kw...) -> SolidModels.to_primitives(sm, el; kw...),
zmap,
Expand Down
22 changes: 22 additions & 0 deletions src/solidmodels/render.jl
Original file line number Diff line number Diff line change
Expand Up @@ -1151,6 +1151,25 @@ function populate_size_fields!(
zmap=(_) -> 0.0,
curvature_sizing=true,
kwargs...
)
DeviceLayout.warn_unknown_render_kwargs(kwargs, :populate_size_fields!)
return populate_size_fields_unchecked!(
cs;
primitives_of,
zmap,
curvature_sizing,
kwargs...
)
end

# For `render_conformal!(sm, sch, target)`, which passes all the target's rendering options,
# including those `render!` declares, after its own render has checked them
function populate_size_fields_unchecked!(
cs::AbstractCoordinateSystem;
primitives_of,
zmap,
curvature_sizing=true,
kwargs...
)
flat = flatten(cs)
clear_mesh_control_points!()
Expand Down Expand Up @@ -1296,6 +1315,8 @@ Available postrendering operations include [`translate!`](@ref), [`extrude_z!`](
Additional keyword arguments are passed to [`DeviceLayout.SolidModels.to_primitives`](@ref) (which falls back to
[`to_polygons`](@ref)) and may be used for
certain entity types to control how entities of `cs` are converted to primitives and added to `sm`.
A keyword argument that is not a known rendering option gives a warning; see
[`DeviceLayout.register_render_kwarg!`](@ref).
"""
function render!(
sm::SolidModel,
Expand Down Expand Up @@ -1425,6 +1446,7 @@ function _render_orchestrator!(
verbose=false,
kwargs...
) where {T}
DeviceLayout.warn_unknown_render_kwargs(kwargs)
t_render = time_ns()
reporter = _step_reporter(verbose)
gmsh.model.set_current(name(sm))
Expand Down
1 change: 1 addition & 0 deletions src/solidmodels/solidmodels_experimental.jl
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ function render!(
previous_stage_level = get(sch.logger.max_level_logged, stage, Logging.Debug)
delete!(sch.logger.max_level_logged, stage)
try
DeviceLayout.reset_render_kwarg_warnings!()
# Route geometry preparation, construction, and postprocessing diagnostics through
# the render stage so the final strictness check sees the complete operation.
reopen_logfile(sch, stage)
Expand Down
10 changes: 9 additions & 1 deletion src/styles.jl
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,11 @@ to_polygons(ent::GeometryEntity, ::MeshSized; kwargs...) = to_polygons(ent; kwar

Style that depends on a Boolean rendering option `flag` with default `default`.

Constructing an `OptionalStyle` registers `flag` as a rendering option, so `render!` doesn't
warn about it. A package that constructs one at top level should call
[`DeviceLayout.register_render_kwarg!`](@ref) for its flag in `__init__`, because
registrations made while precompiling are not kept.

`lowerleft`, `upperright`, `bounds`, `footprint`, and `halo` are forwarded to the
underlying entity styled with the default style.

Expand All @@ -288,7 +293,10 @@ struct OptionalStyle <: GeometryEntityStyle
false_style::GeometryEntityStyle
flag::Symbol
default::Bool
OptionalStyle(a::GeometryEntityStyle, b, c, d) = new(a, b, c, d) # Silence Aqua
function OptionalStyle(a::GeometryEntityStyle, b, c, d)
register_render_kwarg!(c) # So `render!(...; flag=...)` doesn't warn
return new(a, b, c, d) # Silence Aqua
end
end
function OptionalStyle(
true_style::GeometryEntityStyle,
Expand Down
Loading
Loading