Repository navigation
GPU Shell Prepared Contracts
When runtime dependencies are unavailable, GPU continues meaningful roadmap/specification preparation and creates bounded future cards in advance. These two cards are PLANNED decisions. They do not assert available APIs or require Viewer998to wait. Implementation readiness and actual native/integrated/consumer/publication evidence remain distinct.
| Card | Deliverable now | Implementation gate |
|---|---|---|
| #1018 | Existing-capability matrix and exact qualified Shell material/complete-frame proposal | Actual caller need, exact public contract and budgets, clean owned paths/current providers |
| #1019 | Qualified display-pick composition/ownership decision | Named query granularity/precision, Viewer998mode decision, exact DTO/budgets or no-GPU-delta decision |
The following precreated scopes were checked against actual integrated sourcec1bd3a48cf9ca89f5640952608b2b88bdb88e418. Current941uses exactly ref/native/color/edges and fixed lit-color shader; it has no public material binding or picking method. Viewer geometry kinds remain Surface/Curve. Static source observations establish current interface limits, not failed runtime experiments. Existing Surface bindings, native queries and host projection remain candidates for composition.
Roadmap Phase D: an authored two-leaf native Shell scene applies two caller-selected opaque materials; a uniform edit changes only its qualified leaf while source/geometry stay exact. Current #941 source at integratedc1bd3a48 has entries exactly ref/native/color/edges and fixed lit-color drawing. Its public scene has no material bindings. Existing compileMeshMaterial/validateMeshMaterialIR/lowerMeshMaterial and #837/#868 qualified Surface bindings are reusable precedents, not Shell support. Constant RGB already solves static appearance; document this distinction. Duplicate search found #998 and completed941/908/904, but no Shell material-contract card.
GPU owns this preparation card and its GPU Wiki page. PLANNED specification work; no runtime API or implementation claim. Keep #1010's temporary manifest/config/instruction transfer and all native receipts intact. Viewer #998 remains an independent available-provider facade adoption; this card must not become a new dependency gate for its first RGB/lighting scene. No shared/root/lock/product edits.
Before any later implementation, freeze exact clean parent, paths, public signatures/DTO/schema/version, original versus derived coordinates, identity, copies, budgets, errors and compatibility in the Issue and Wiki. A specification can conclude that existing capabilities suffice and no GPU code is required. Do not create a duplicate feature card or manufacture producer readiness. Separate specification, native implementation, local Integration, named consumer and publication stages.
- Inspect actual current public Shell/Surface material exports and record a composition table: supported unchanged, GPU binding gap, Viewer routing, Loader routing. No source mutation or producer replay.
- Identify the actual caller binding requirement and its link; #998 first adoption is not obliged to implement it. If only constant colors are needed, retain #941 unchanged and record no new backend needed.
- Freeze an additive complete Shell appearance/frame proposal separately from sceneV0. Decide exact qualification {graphId,graphRevision,featureId,outputSlotId}, zero/empty leaves, nonpresent/duplicate/stale refs, dense bindings/default colors, copied IR/source/uniform snapshots, and whole-frame atomic replacement. Preserve original F64/source/UV/face/Shell/Curve IDs and one rawXYZ/mm display conversion.
- Reuse the actual compiler version/profile and admitted source/uniform ranges. Declare linear color, existing gamma2.2 and lighting/normal order exactly once. Native UV is not a texture coordinate. Edge preview remains explicit and separate. No arbitrary GLSL/textures/PBR/alpha/deformation scope.
- Retain existing four-leaf geometry caps384v/288tri/192paths/80faces/8Shells per entry; aggregate1536/1152/768/320/32 and77568geometry-array bytes. Specify program sharing and accepted-plus-staged shader/program/buffer/attachment caps from real lowering. Existing prg4/shader4/VAO16/buf40/attachment2 budgets must not be silently exceeded. Exact new limits need a measured admission/work rationale before implementation.
- Freeze error categories, ranged compile diagnostics, invalid imported IR/uniform/getter/ref handling, late shader/allocation failure rollback, resize/context loss/disposal and absent-material legacy compatibility. State source-default versus explicit compiled checkpoint paths after actual1010/1016receipt.
Authentic #927 graph with two selected #896 leaves and repeated local native IDs under distinct qualification; two real source-compiled materials; edit one leaf uniform and independently check resulting RGB. Confirm native uploaded geometry/source/UV/IDs unchanged, all triangles before true edges/shared depth and exact default reset. Invalid ref/IR/uniform and late program failure retain whole prior CPU frame/pixels/handles; live console/GL0 and disposal0. This is the proposed implementing card's single affected-build/actual-WebGL2 flow, not executed evidence.
Publish the decision table and exact proposal/open decisions in GPU Wiki and this Issue. Implementation starts only after a concrete consumer need, complete public contract, actual providers and owned clean paths are settled. No required API name/version is invented in this preparation card. If the gap remains justified, convert this same bounded card with its frozen implementation scope or link one necessary child; keep history. No publication or broad gallery/performance/packed/Review campaign.
Checked immutable accepted GPU source in clean native tree71d895fa735bd64f4ea004b70de602dce044d6c9, whose Shell/compiler blobs are inherited from the accepted941/974/975providers. Integration is actively editing six manifests for1010; those uncommitted files are not provider acceptance and were not changed by GPU. No runtime experiment was repeated. Two initial guessed filenames (mesh-material-binding.ts/native-mesh-draw.ts) were absent; actual implementations are mesh-material.ts and mesh-shaders.ts. This was source discovery, not a build/product failure.
| Requirement | Actual current capability | Proposed responsibility |
|---|---|---|
| Different static leaf colors | BooleanShellSceneEntry has RGB and explicit edge color; lit-color shader already supported | Caller/GPU existing scene, no new code needed |
| Source parsing, reconstructed imported IR and trusted lowering | Public compileMeshMaterial/validateMeshMaterialIR/lowerMeshMaterial, IRversion0/profilemesh-opaque-fragment-v0 | Reuse existing GPU compiler |
| Uniform binding validation | MeshMaterialBinding type is public; validateMeshMaterialBinding function is internal in mesh-material.ts | Reuse internally; do not invent a public validator export |
| Shader and uniform application | Internal materialMeshShaders/applyMeshMaterial already used by MeshRenderer/PrimitiveSceneRenderer | Reuse GPU lowering/lighting; no new kernel |
| Qualified Shell material application | Shell scene only admits ref/native/color/edges; shared fixed program has no binding state | Exact additional GPU transaction only if caller needs authored materials |
| Viewer/Loader Shell appearance | First Viewer998appearance is RGB/lighting; routing/file persistence has separate ownership | Owner's later consumer contract, not a prerequisite for998 |
Proposed separate complete frame: exact own plain fields {version:0,scene,options,materials} where scene stays existingBooleanShellSceneInputV0 and options stay existingBooleanShellSceneOptions. Materials is a dense0..4array of exact {ref,binding}. Ref is the existing four-field BooleanShellLeafRef, unique and present in the candidate scene; missing/wrong revision or duplicate qualification refuses the whole frame. Empty native leaves remain admitted and may retain a binding with no geometry draw. Empty scene requires empty materials. A missing binding uses its existing scene RGB. Ref equality is case-sensitive and does not depend on native IDs or source shaderId. The caller still owns actual CAD graph association. No particle/cloth/primitive frame cohabitation is proposed here.
Proposed compatibility: additive complete-frame mount/update/getter names remain undecided until the actual caller contract. Full complete-frame replacement commits scene/options/materials together. Existing update(scene,options) preserves its legacy no-material behavior and clears accepted bindings after successful replacement; rejected update retains everything. setOptions, resize and render retain complete copied appearance. Disposal is idempotent. CPU getters remain available after context loss as currently documented, while new GL work/readPixels refuse and remount is required. No mutation of sceneV0's exact entry schema, native F64/control/UV/IDs or caller source.
Color and authority: reuse materialMeshShaders, which replaces the existing color gamma-decode term with already-linear trusted material expression, then applies existing lighting and one gamma2.2 output encode. Source RGB literals are decoded by the current compiler. Fixed RGB without a binding remains byte-compatible with existing shaders. Original hard normals and rawXYZ/mm positive scale/translation remain. True-edge preview uses its existing flat RGB; material expressions do not color edges or interpret native UV.
Proposed work/handle admission: keep the existing four-leaf/native geometry limits and77568geometry-array bytes per frame; staged plus accepted geometry is at most155136derived-array bytes. Per binding keep current64KiB source,16floatuniforms,16locals,256charged work/depth16 and internal own-data8192visits/depth24. Four material sources total≤262144UTF8bytes per frame; copied accepted plus candidate≤524288source bytes, excluding object overhead. Up to64uniform slots per frame. Each lowered fragment plus declarations must additionally be≤65536UTF8bytes before GL allocation (a proposed new admission check, not measured support).
At most four triangle programs (one per occupied leaf including shared default) plus one shared edge program; accepted plus candidate live programs≤10. Compile sequentially and detach/delete temporary shaders after each link; live temporary shaders≤2. Keep VAO≤16,buffer≤40,FBO/texture/depth≤2 each across accepted/candidate. This is an explicit proposal to widen only program admission from current4to10, with a future maximum-material/late-failure actual witness; it is neither a physical memory/performance measurement nor automatically granted support. No global or persistent program cache is needed.
Atomic failures: retain current whole candidate framebuffer/geometry staging; validate source/IR/ranges/qualification before allocating. MeshMaterialError retains actual INPUT/IR/UNIFORM/BUDGET/RANGE categories; scene schema/ref/native failures retain RangeError; allocation/GL/lifecycle failures retain GPUError and current UpdateResult shape. Getter traps are rejected without invocation. A fourth-leaf or final-edge program failure must release only candidates and restore accepted frame/pixels/metadata/resources, including after a failed resize. No two-phase host apply pretending to be one GPU transaction.
Open gates: actual named caller/source-uniform scenario; accepted complete public method names and version; maximum-program/lowered-text admission witness; precise resize failure behavior; clean source-default/compiled-checkpoint provider receipts. These decisions are detailed preparation, not a claim that1018implementation is ready. When settled, use the authentic two-leaf source acceptance already defined in the card.
Roadmap Phase C: a caller points at an authentic multi-leaf Shell display with overlapping native IDs and receives current qualified lineage, then scene replacement invalidates the old selection. Current #941 provides copied scene/native provenance, genuine sampled edge paths and shared depth but no public pick method. Viewer public geometry kinds are Surface/Curve; #998 explicitly owns deciding first Shell picking support or deferral. Existing #584 hole-face screen selection, CAD581/655 native queries and Viewer977 filters have different scopes and must be tested as composition candidates before any GPU API is proposed. Duplicate search found these related cards and #998, not a dedicated GPU composition/contract decision.
GPU owns this preparation card and its GPU Wiki page. PLANNED specification work; no runtime API or implementation claim. Keep #1010's temporary manifest/config/instruction transfer and all native receipts intact. Viewer #998 remains an independent available-provider facade adoption; this card must not become a new dependency gate for its first RGB/lighting scene. No shared/root/lock/product edits.
Before any later implementation, freeze exact clean parent, paths, public signatures/DTO/schema/version, original versus derived coordinates, identity, copies, budgets, errors and compatibility in the Issue and Wiki. A specification can conclude that existing capabilities suffice and no GPU code is required. Do not create a duplicate feature card or manufacture producer readiness. Separate specification, native implementation, local Integration, named consumer and publication stages.
- Record exact public observations available from941, current camera projection/unprojection and authentic896face/edge/triangle provenance. Determine whether a caller can implement its declared approximate display query without new GPU source.
- Align with998's actual Shell mode decision. A deferred Viewer pick is a documented limit, not evidence that a GPU kernel is necessary. GPU only prepares missing backend observations; Viewer owns facade/UI/highlight, CAD owns certified geometry queries/tolerances.
- Decide leaf-only versus derived triangle/face versus sampled edge display granularity for a named caller. Freeze CSS/device/framebuffer pixel mapping, RH authoredXYZ/mm and one scale/translation, camera state, front/back visibility, depth/occlusion, ties/ambiguity, empty geometry and finite screen tolerance. Never label sampled display hits certified native hits.
- Preserve full graph/revision/feature/output qualification and original native IDs; include an accepted-frame/revision token and stale-result refusal. Define copied result ownership, explicit no-hit versus ambiguity, errors/getter refusal and caller mutation. Do not persist derived triangle indices as native identity.
- Bound observations/work by admitted geometry1536v/1152tri/768paths/320faces/32Shells, up to1536sampled lines and frame dimensions1..4096/area4194304. Evaluate a CPU composition before adding readback/program/resources. Any new buffer/resource budget requires its own exact contract; no silent GPU or CAD widening.
- Document original source/UV/IDs unchanged, camera/resize/replacement/clear/context-loss/disposal compatibility and selection-feedback ownership. Selection must not require a second canvas or external renderer.
Authentic927two-leaf/current896mesh controls with a real hole and overlapping projected regions. Independently project known cap/edge/miss points; test near-alone/far-alone and combined reordered entries, qualified overlapping IDs, hole miss, equal-depth ambiguity/order decision, explicit edge tolerance, camera/resize and stale revision after replacement. Original geometry and all source associations remain intact. Actual shared-depth pixels/console/GL0 and disposal0 are required only if later runtime rendering code is necessary. No full viewport/gallery/producer replay.
Publish the existing-capability/ownership matrix and decision in Wiki/Issue. Exact named consumer query semantics and998relationship must be settled before any GPU implementation. Choose and record one outcome: caller composition/no GPU delta; precise missing observation with frozen additive DTO/API; or blocked native precision dependency. Keep unresolved decisions explicit. This card is not a promise of certified picking or an implementation assignment to Viewer/CAD.
A reused scoped read-only helper inspected acceptedc1bd3a48cf9ca89f5640952608b2b88bdb88e418 via git show, with no product writes or producer/renderer execution. Root owns this final specification. Decision: current public data is sufficient for a host-owned approximate qualified-leaf triangle selector; no new GPU observation API is justified by that scope. This is a source/composition decision, not actual pick correctness or a Viewer feature claim.
| Observation needed | Accepted public capability | Exact source |
|---|---|---|
| Mesh and complete leaf qualification | copied renderer.scene includes native mesh positionsMM/indices and graph/revision/feature/output tuple | boolean-shell-scene-renderer.ts scene getter; boolean-shell-scene-input.ts types |
| Actual derived display coordinates | public prepareBooleanShellBuffers reproduces admitted F32positions/U16indices from rawXYZ×scale+translate | index.ts; boolean-shell-buffers.ts; native-mesh-buffers.ts |
| Accepted camera/conversion | copied renderer.options includes required camera, mmToSceneUnit and translate | Shell renderer options getter |
| Actual projection | public validateMeshCamera/prepareCamera yields column-major F32view/projection | index.ts; camera.ts |
| Bounds and empty | copied aggregate bounds; empty checks every entry's triangle count | Shell renderer getters |
| CSS/backing dimensions | host owns supplied canvas.width/height and CSS rect; GPU has no width/height getter | Shell resize and host canvas |
| Pixel/native precision | readPixels exposes RGBA only; no depth-readback/unprojection/pick API | index exports and renderer readPixels |
Use actual indices rather than AABBs, so genuine holes and empty outputs remain misses. Host handles CSS→backing pointer conversion, clipping and two-sided triangle queries with actual public camera matrices and derived positions; no native coefficient mutation, implicit unit/axis transform or new renderer. At most4leaves/1152triangles. Return complete current qualified leaf lineage; derived triangle index is temporary display bookkeeping, never persistent native identity. Host increments an accepted-frame generation after scene/camera/resize replacement and refuses older results even if native graph revision is unchanged. No GPU-owned token or automatic graph association is assumed.
Rendering has DEPTH_COMPONENT24, opaque fillsLESS/depth-write/culling-off; all fills precede true-edge preview linesLEQUAL/no-write. Fills with edges enable polygonoffset(1,1). Therefore close/intersecting/equal-depth candidates need an explicit host ambiguity policy; input-order fill ties, depth quantization, polygon bias, clipping and edge rasterization cannot be presented as exact CPU/pixel equivalence. This initial proposed selector returns leaf-only filled-triangle candidates; genuine edge identity and exact native ray/UV/topology require separate CAD/consumer contracts. Bounds-only or RGBA color matching are not acceptable substitutes.
Copied scene/options/bounds/empty are readable after context loss until disposal, but the host must observe its owned canvas loss event and disable visible picking until a valid presentation exists. Current GPU has no public lost-state getter; that omission does not require a new API because the host owns the canvas event. Use renderer.resize for backing dimensions, not arbitrary canvas mutation. Existing Viewer projectNativePoint/pick methods apply only to its Surface/Curve inventory; they are not generic Shell queries.
Ownership/result: host/Viewer owns pointer mapping, clipping/ray math, ambiguity, frame generation, qualified graph association and selection feedback. GPU supplies accepted copied data/matrices/admitted buffers; CAD supplies certified native queries/tolerance/topology. Do not make Viewer998wait for a new backend. A bounded actual host flow can use the previously defined authentic two-leaf/hole/near-far/camera/stale controls once its named consumer, exact ambiguity/tolerance/result DTO and owned example paths are frozen. Edge selection and native certification remain unresolved separate requirements. No public pick function, runtime acceptance or broad campaign was added here.
- Maintain actual provider/consumer receipt links and explain each missing gate; update only on new evidence.
- Complete the existing-capability and ownership matrix using current exported source. Name an actual caller scenario; no kernel API is required solely by a planning direction.
- Resolve decisions and publish the exact version/frame/unit/identity/copies/budget/error/compatibility contract in the same card. Use a bounded child only for a distinct necessary implementation.
- Mark READY only once the actual dependencies and owned clean paths exist. Then implement, run the affected build and one short actual flow, hand the immutable delta once and select the next ready owned card.
- If code remains blocked, advance another useful preparation item. Keep unchanged polling quiet. Do not rerun already accepted producer flows or inflate the queue with duplicate or hypothetical work.
GPU roadmap · GPU manual · Viewer Shell adoption #998 · Current capability map.
The actual editor architecture proposal separates CAD asset editing from render-scene appearance. It is a proposal, with no new Execute host or path transfer. Its first scene-source milestone uses existing GPU scene APIs and does not need #1018/#1019. A native Surface appearance milestone can use the current qualified Viewer Surface method; this does not establish generic Shell support.
Before turning #1018 into implementation, the caller must name the admitted native asset route, full graph/feature/output qualification, whether different Shell leaves need separate source/uniforms, and the accepted-only file Open transaction. Fixed RGB/lighting remains sufficient for a caller that does not author material expressions. Surface authoring stays on its existing API. Persist original source/uniforms and qualified native references; derived IR/GLSL/F32 buffers are regenerated, not saved as native authority.
The current Shell proposal would atomically admit GPU geometry/camera/material state, but Viewer loading and multiple material calls are separate operations. An editor cannot label those calls a whole-file transaction merely because GPU has a complete-frame design. Viewer/host must settle the candidate swap or its own minimal public seam, in its owned card. Selection highlight restrictions require a caller-owned authoring target; #1019's approximate leaf query remains host-owned and is not required for an initial no-pick route.
Accepted1010source defaults and delivered1016compiled references remove the earlier provider gate. Actual caller choice, names/version, maximum-program/lowered-text witness and resize rollback are still the precise #1018 start gates. No native runtime, editor progress, picking or publication is claimed by this preparation update.
#1043 CAD Editor and #1047 Render Editor now have independent claimed package/app lanes and frozen startup workflows. They are not completed editor evidence. The Render Editor Stage3 roadmap explicitly starts with current qualified Surface material bindings/public lighting; neither startup1047 nor that existing Surface path establishes a distinct Shell-leaf material requirement. #1018 remains PLANNED until a real caller selects qualified Shell output/per-leaf source or uniforms and the exact complete-frame/API/resource/resize contract. #1019 remains host approximate selection composition with its recorded ambiguity/clip/query decision; no new GPU observation API is justified. These newer actual ownership facts supersede older proposal-only1029 wording while preserving historical receipts.
A different actual future requirement, Render Editor Stage5 mutual SDF/native depth, is prepared under #1059. It does not widen Shell material/selection or impose a startup dependency. Current public999 remains unavailable and1003 still lacks dynamic826GO; current Issue receipts were checked during this preparation. No producer replay or runtime support was invented.
Actual Viewer1063 design receipt6085165000 now supplies the previously missing named query caller. Its proposed pickShell result retains qualified graphId/graphRevision/featureId/outputSlotId, derived triangle index/display point/positive view depth, approximate:true and ambiguity. It uses current public prepareBooleanShellBuffers/prepareCamera, a CPU near-to-far triangle query and no GPU allocation/readback/state mutation. Max4leaves/1152triangles and global-min-depth tolerance1e-6scene with deterministic qualified tie order are explicit proposals, not executed pixel/native certificates. Exact intersection/singularity tolerances and actual adopted998 base remain Viewer-owned before-code gates.
GPU1019 ownership/existing-capability decision is now concrete: no new GPU pick/unprojection/depth API is justified. Original source/buffers/camera getter seams suffice. GPU does not copy Viewer CPU query or make its runtime available. Filled two-sided triangles versus edge polygonoffset/LEQUAL and native UV/persistent topology remain distinct. Source audit and consumer design are preparation; Viewer1063 actual query/UI/retention/lifecycle receipt still pending. Historical proposal-only998 wording is retained. No new Issue, root/runtime/producer/build replay or routine Planner notice.
Canonical Viewer #1063 is CLOSED. Native 20b3a8dca91a672ba3240f5847319304860bd904 -> 483c39a6b65f7f67eb59d8c97f65e215159dc492 was adopted at 04f68a5c48c2b826f811ae93e5ec7de806dc08df. Native receipt6094257603 and closure audit6096703310 replace the earlier pending-consumer status. This reconciliation runs no build, browser or completed flow again.
The actual consumer pickShell({xCss,yCss}) returns independent full qualified reference, derived triangle, scene point, positive prepared view depth, approximate/ambiguity or null. Existing GPU copied Shell buffers and camera supply the observations; Viewer owns the CPU query and facade. Its bounded native source/compiled/physical flows covered near/far, holes, two-sided/global-min1e-6 ties without pairwise chaining, copies/getter0, Inspect, candidate retention, stale/loss/unavailable and normal disposal. The actual original receipt controls its browser and numerical scope. Preserve the 9,773,021-byte recording failure and compact-driver rerun; no product repair occurred.
Decision: preparation complete; existing composition suffices; no GPU pick/unprojection/readback API or runtime delta. This is the completion outcome explicitly permitted by #1019. No new assignment, duplicate card or blanket gate for Viewer #998 follows. #1018 still needs a real distinct Shell-leaf authored material caller.
Limits remain F32 triangles/camera plus CPU binary64 inversion, approximate displayed triangles rather than certified native UV/topology/raster/Depth24/precision equivalence. Identical external SDK reload has no observable generation token. Sticky-loss/unavailable queries refuse; explicit lost-context deletion0 is unclaimed. CurrentRoot #674/#1254, editor files/history and publication remain separate. The historical proposal stays preserved below; its pending wording is superseded by this dated reconciliation.
Viewer #1369 CPU provider is adopted at880e2373 (receipt6100956533). Its actual appearance materials target visible candidate Surface refs {modelId,surfaceId} and carry existing MeshMaterialBinding source/uniforms. It returns an ordinary complete Surface/Curve frame through GPU preflight; this is a concrete authored Surface material caller. No Shell-leaf material DTO or distinct per-leaf Shell shader requirement follows from this API.
GPU complete-frame boundary preparation now records visible-only material eligibility, empty visibility/materials[], proposed coherent Viewport selection and accepted-state ownership under existing #1375. #1018 retains its exact missing requirement: an actual caller selecting qualified Shell output with distinct per-leaf materials, qualified identity and agreed resource/error/complete-frame semantics. No producer availability, GPU runtime delta or publication is inferred. #1019's completed existing-composition outcome is preserved; it is not reopened by this Surface requirement. No completed provider/browser flow replay or new Issue.