[Docs] (Pipe): say what actually fails to publish a program, a pipeline and a shader dying, instead of naming a scope

- the kUnpublishedDestroy note said the three kinds were outside the six D13 scopes explicit
  destroy to; the tree's reason is sharper and does not depend on reading D13's prose one way
  or the other: those three have no per-object handle on the wire at all, so their DirectGLES
  twins are still reclaimed by the backend's own registry teardown
- records the brief/tree disagreement in place: D13 says "six kinds" while the Core.cpp line
  ranges it cites also cover MarkProgram/MarkShaderForDeletion
This commit is contained in:
2026-09-07 23:18:09 -04:00
parent 5d4d91fe7e
commit 067b186677
+20 -15
View File
@@ -40,19 +40,24 @@
// mutation is published inline and needs no shutter at all. // mutation is published inline and needs no shutter at all.
// kReverseChannel not state: a write INTO the frontend from the backend's side. // kReverseChannel not state: a write INTO the frontend from the backend's side.
// kNoBackendRead no backend read point observes this state at all. // kNoBackendRead no backend read point observes this state at all.
// kExplicitDestroy published by the delete_* call the Track H slice emits when the // kExplicitDestroy published by the delete_* / resource_destroy call the Track H slice
// object's last reference drops - an object's DEATH, which no // emits when the object's last reference drops - an object's DEATH,
// generation shutters because there is no longer an object to carry // which no generation shutters because there is no longer an object
// one. Only the six object kinds P2 brief D13 scopes Espryt 0b's // to carry one. Only for a kind that HAS an identity on the wire to
// explicit destroy to (buffers, framebuffers, renderbuffers, // destroy: the resources and CSOs of PipeCalls.def, which is what P2
// samplers, textures, vertex arrays) may use this answer. // brief D13 scopes Espryt 0b's explicit destroy to.
// kUnpublishedDestroy // kUnpublishedDestroy
// the same event for a kind NO call publishes yet: programs, program // the same event for a kind NOTHING publishes: a program, a program
// pipelines and shaders are outside D13's six, so their death reaches // pipeline and a shader have no per-object handle on the wire at all
// a backend only through the object's own teardown path. Recorded as // in P2 - resource_destroy and the delete_* family name resources and
// a hole rather than dressed up as a mechanism that exists - naming // CSOs - so their DirectGLES twins are still reclaimed by the
// kExplicitDestroy here would be the same defect the RenderState // backend's own registry teardown and no frontend call says they
// check above exists to stop, one class down in stakes. // died. Recorded as a hole rather than dressed up as a mechanism that
// exists; naming kExplicitDestroy here would be the same defect the
// RenderState derivation above exists to stop, one class down in
// stakes. (D13's prose says 'six kinds' while the Core.cpp ranges it
// cites also cover MarkProgram/MarkShaderForDeletion; the tree
// decides, and the tree has no wire object for those three.)
// kPulledEveryVerb no shutter exists, and none is needed yet: the PipeInputs field this // kPulledEveryVerb no shutter exists, and none is needed yet: the PipeInputs field this
// writes is in its verb class's may-read mask, so the residual fill copies // writes is in its verb class's may-read mask, so the residual fill copies
// it at EVERY verb of that class. A shutter here is a P3/P4 optimisation, // it at EVERY verb of that class. A shutter here is a P3/P4 optimisation,
@@ -148,9 +153,9 @@
X(BumpTextureBindGeneration, NEW_SAMPLER_VIEWS) \ X(BumpTextureBindGeneration, NEW_SAMPLER_VIEWS) \
X(SetNamedTransformFeedbackBinding, NEW_SO_TARGETS) \ X(SetNamedTransformFeedbackBinding, NEW_SO_TARGETS) \
/* ---- an object's death: no generation, because there is no longer an object */ \ /* ---- an object's death: no generation, because there is no longer an object */ \
/* to carry one. Espryt 0b's delete_* publishes the six kinds D13 scopes it to; */ \ /* to carry one. Espryt 0b's delete_* / resource_destroy publishes the kinds */ \
/* programs, program pipelines and shaders are NOT among them and nothing else */ \ /* that have a handle on the wire; programs, program pipelines and shaders have */ \
/* publishes their death, so they answer kUnpublishedDestroy - a recorded hole. */ \ /* none in P2, so nothing publishes theirs - kUnpublishedDestroy, a known hole. */ \
X(MarkBufferObjectForDeletion, kExplicitDestroy) \ X(MarkBufferObjectForDeletion, kExplicitDestroy) \
X(MarkFramebufferObjectForDeletion, kExplicitDestroy) \ X(MarkFramebufferObjectForDeletion, kExplicitDestroy) \
X(MarkProgramForDeletion, kUnpublishedDestroy) \ X(MarkProgramForDeletion, kUnpublishedDestroy) \