Documentation
¶
Overview ¶
Package stencilblit writes the stencil aspect of a depth/stencil texture with render passes, for backends that cannot copy a buffer into it.
OpenGL ES has no way to upload only the stencil of a combined depth/stencil format (DEPTH24_STENCIL8, DEPTH32F_STENCIL8): the pixel transfer of glTexSubImage2D writes both aspects or, with STENCIL_INDEX, needs GL 4.4 / ES 3.2 and a stencil-only internal format. Dawn lowers such a copy in the frontend (src/dawn/native/BlitBufferToDepthStencil.cpp, BlitR8ToStencil), and so do we:
- the stencil bytes are copied into an R8Uint texture of the copy extent;
- for each destination array layer, one render pass on a view of that mip and layer loads and stores depth and stencil, draws a full-screen triangle with the clear pipeline (reference 0, Replace, write mask 0xFF: every stencil bit of the copied texels becomes 0), then once per bit with a pipeline whose write mask is that bit (reference 0xFF, Replace), whose fragment shader discards the texels where the bit is 0.
Depth is neither tested nor written (depthCompare Always, depthWriteEnabled false), so the depth aspect keeps its contents.
This package owns the shaders, the pipeline state, the per-device cache of pipelines and the order of the commands. The caller (the root package) creates the resources through its public API and records through a Pass, so the rule lives in one place and this package imports nothing of the caller (ADR-069).
Index ¶
- Constants
- Variables
- func BitEntryPoint(bit int) string
- func RecordLayer[P any](pass Pass[P], pipelines *Pipelines[P], x, y, width, height uint32)
- func ShaderSource(dim gputypes.TextureViewDimension) (string, error)
- func SourceViewDimension(layers uint32) gputypes.TextureViewDimension
- type Cache
- type Key
- type Params
- type Pass
- type Pipelines
- type StencilState
Constants ¶
const ( VertexEntryPoint = "vs_main" ClearEntryPoint = "fs_clear" )
Entry points of the blit shader.
const ( SourceBinding = 0 ParamsBinding = 1 )
Bindings of the blit bind group: the R8Uint source view and the Params uniform.
const ( ClearReference uint32 = 0 BitReference uint32 = 0xFF )
ClearReference and BitReference are the stencil references of the clear pipeline and of the bit pipelines.
const ParamsSize = 16
ParamsSize is the size in bytes of the uniform Params of one layer.
const StencilBits = 8
StencilBits is the number of bits of every WebGPU stencil format.
const VertexCount = 3
VertexCount is the vertex count of the full-screen triangle.
Variables ¶
var ErrDisposed = errors.New("stencilblit: cache disposed")
ErrDisposed is returned by Cache.Get after Cache.Dispose.
Functions ¶
func BitEntryPoint ¶
BitEntryPoint returns the fragment entry point of bit.
func RecordLayer ¶
RecordLayer records the blit of one layer: the clear draw, then one draw per stencil bit. x, y, width and height are the copied rectangle of the destination mip level; fragments outside it keep their stencil.
Dawn passes the bit to one shader through firstInstance; this package bakes it into one fragment entry point per bit instead, because a base instance is not available on every OpenGL ES (it needs GL 4.2 or EXT_base_instance), the backend this blit exists for.
func ShaderSource ¶
func ShaderSource(dim gputypes.TextureViewDimension) (string, error)
ShaderSource returns the WGSL of the blit for a source view of dim (2d or 2d-array): the full-screen triangle, the clear fragment entry point and one fragment entry point per stencil bit, each with its bit baked in as a constant.
Dawn's shader (BlitBufferToDepthStencil.cpp, kBlitStencilShaderCommon) reads the bit from the instance index; see RecordLayer for why we bake it.
The mip level is an i32: naga's GLSL writer passes a u32 level to texelFetch, textureSize and textureQueryLevels as it is, and GLSL takes an int there with no implicit conversion, so the GL driver rejects the shader.
func SourceViewDimension ¶
func SourceViewDimension(layers uint32) gputypes.TextureViewDimension
SourceViewDimension returns the dimension of the R8Uint source view of a copy of layers array layers.
Types ¶
type Cache ¶
type Cache[E any] struct { // contains filtered or unexported fields }
Cache holds the pipelines of each Key of one device, built on first use. E is the caller's entry: the pipelines and whatever they need (shader module, layouts). It is safe for concurrent use.
func (*Cache[E]) Dispose ¶
func (c *Cache[E]) Dispose()
Dispose releases every entry. Later calls of Get return ErrDisposed, and later calls of Dispose do nothing.
type Key ¶
type Key struct {
Format gputypes.TextureFormat
ViewDimension gputypes.TextureViewDimension
}
Key selects the pipelines of one blit: the destination format (the pipelines' depth/stencil state format) and the dimension of the source view, which the shader's texture type follows.
Dawn keys its cache the same way (BlitBufferToDepthStencil.cpp, GetOrCreateR8ToStencilPipelines keyed by format and view dimension).
type Params ¶
type Params struct {
// OriginX and OriginY are the copy's origin in the destination mip
// level; the source texel of a fragment is its position minus origin.
OriginX, OriginY uint32
// Layer is the source array layer of the pass (2d-array view only).
Layer uint32
}
Params are the uniform values of the pass of one layer.
func (Params) Bytes ¶
func (p Params) Bytes() [ParamsSize]byte
Bytes returns p as the WGSL struct Params (origin: vec2u, layer: u32), padded to ParamsSize.
type Pass ¶
type Pass[P any] interface { SetPipeline(p P) SetStencilReference(ref uint32) SetScissorRect(x, y, width, height uint32) Draw(vertexCount, instanceCount, firstVertex, firstInstance uint32) }
Pass records the commands of one layer into a render pass the caller opened on the destination view, with the layer's bind group set.
type Pipelines ¶
type Pipelines[P any] struct { Clear P Bits [StencilBits]P }
Pipelines are the render pipelines of one Key.
type StencilState ¶
type StencilState struct {
Compare gputypes.CompareFunction
FailOp gputypes.StencilOperation
DepthFail gputypes.StencilOperation
PassOp gputypes.StencilOperation
ReadMask uint32
WriteMask uint32
}
StencilState is the stencil state of one blit pipeline, the same for the front and back faces.
func BitState ¶
func BitState(bit int) StencilState
BitState is the stencil state of the pipeline of bit: only that bit is written, from the reference BitReference, where the fragment is kept.
func ClearState ¶
func ClearState() StencilState
ClearState is the stencil state of the clear pipeline: every bit of each covered texel takes the reference 0.
Source Files