docs: align apply-template guides with deferred-rounding pipeline#4
Open
giardiello wants to merge 1 commit into
Open
docs: align apply-template guides with deferred-rounding pipeline#4giardiello wants to merge 1 commit into
giardiello wants to merge 1 commit into
Conversation
The template pipeline no longer rounds during Phase 5 -- rounding has
been consolidated into a single late pass (Phase 9b) after crop, and
the rounding model itself has changed. The docs were still describing
the old "round everything to integers after scaling" behaviour. This
brings both implementer-facing guides in sync with the current code
(native/core/src/fdl_template.cpp + fdl_geometry.cpp).
Changes
-------
FDL_Apply_Template_Logic.md
- Pipeline ASCII diagram: replace "5. Scale & Round" with
"5. Scale (float)" and add "9b. Round & Absorb" before step 10.
- Step 5 renamed to "Scale (no rounding)"; rounding language removed;
note that scaled_bounding_box is captured pre-round as a float and
stored on the output as _scaled_bounding_box.
- New Step 9b "Round Integer-Typed Schema Fields" with the full
algorithm:
* canvas rounded per RoundStrategy; effective always ceil'd
* protection / framing / all anchors stay float
* ceil delta absorbed into effective_anchor as -delta/2
* canvas delta shifted symmetrically (+delta/2) into all anchors
* per-axis clamp: preserve inner anchors, shrink dims; for
effective use floor(canvas-anchor) to keep the integer invariant
* hierarchy re-established after the floor step
- Step 10 custom-attributes description updated: _scaled_bounding_box
and _content_translation are unrounded floats by design; may differ
by sub-pixel amounts from the rounded canvas.dimensions.
- "Complete Formula Reference" header updated: inputs are floats,
integerization happens later.
FDL_Template_Implementer_Guide.md
- Section 2.1 ops table: fdl_geometry_round() description updated.
- Section 4.5 rewritten for the no-rounding Phase 5 semantics.
- New section 4.9 "Phase 9b: Round Integer-Typed Schema Fields" with
pseudocode mirroring geometry_round() in the core.
- Section 5.6 "Exact Integer Comparison" renamed to "Exact Float
Comparison"; explains why FIT detection stays bit-exact despite
Phase 5 no longer rounding.
- Section 6.1: canvas/effective annotated as integer "after Phase 9b";
inner dims and anchors annotated as float; custom-attributes table
clarifies that _scaled_bounding_box and _content_translation are
post-scale, pre-round.
- Section 7 formula: inputs annotated as floats.
- Section 8 summary table: phase 5 renamed, phase 9b added; "Round
early" design decision replaced with "Round late, absorb into
anchors"; "Exact integer comparison" restated as exact FIT detection
via variable identity; added a 7th decision about the unrounded
side-channel for imaging.
svg/02_pipeline_overview.svg
- Phase 5 label updated.
- New Phase 9b box inserted between Phase 8 and the (now Phase 10)
output step; viewBox and background extended by 76px to fit.
No code changes. Both guides now match Adam's ef57e1f rounding
pipeline and the fractional-pixels model downstream consumers rely on.
Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Both implementer-facing docs (
FDL_Apply_Template_Logic.mdandFDL_Template_Implementer_Guide.md) were still describing the old "round everything to integers after scaling" behaviour. The pipeline has been reshaped around Adam's `ef57e1f6` rounding work:canvas.dimensionsandcanvas.effective_dimensionsare integerized.protection_dimensions, framingdimensions, and all anchors stay float per the "fractional pixels" model.effective_dimsis alwaysceil'd -- the template'sRoundStrategyonly applies tocanvas.dimensions._scaled_bounding_boxand_content_translationare exported as custom attributes in their pre-round float form, so image processors (e.g. `fdl_imaging`'s warp-based pipeline) can place content at sub-pixel precision without re-quantizing.This PR is docs-only -- no code changes. It brings both guides in sync with the current `native/core` code at `ef57e1f6`.
Changes
`FDL_Apply_Template_Logic.md`
`FDL_Template_Implementer_Guide.md`
`docs/svg/02_pipeline_overview.svg`
Test plan
Docs-only change -- no tests affected. Verification:
Base
Based on `base/adam-ef57e1f6`. The docs on that base are identical to those on `origin/dev`, so this change can be re-targeted to `origin/dev` once Adam's rounding work lands upstream.
Made with Cursor