Module gles

Source
Available on gles only.
Expand description

GLES API internals.

§OpenGL ES3 API (aka GLES3).

Designed to work on Linux and Android, with context provided by EGL.

§Texture views

GLES3 doesn’t really have separate texture view objects. We have to remember the original texture and the sub-range into it. Problem is, however, that there is no way to expose a subset of array layers or mip levels of a sampled texture.

§Binding model

Binding model is very different from WebGPU, especially with regards to samplers. GLES3 has sampler objects, but they aren’t separately bindable to the shaders. Each sampled texture is exposed to the shader as a combined texture-sampler binding.

When building the pipeline layout, we linearize binding entries based on the groups (uniform/storage buffers, uniform/storage textures), and record the mapping into BindGroupLayoutInfo. When a pipeline gets created, and we track all the texture-sampler associations from the static use in the shader. We only support at most one sampler used with each texture so far. The linear index of this sampler is stored per texture slot in SamplerBindMap array.

The texture-sampler pairs get potentially invalidated in 2 places:

  • when a new pipeline is set, we update the linear indices of associated samplers
  • when a new bind group is set, we update both the textures and the samplers

We expect that the changes to sampler states between any 2 pipelines of the same layout will be minimal, if any.

§Vertex data

Generally, vertex buffers are marked as dirty and lazily bound on draw.

GLES3 doesn’t support first_instance semantics. However, it’s easy to support, since we are forced to do late binding anyway. We just adjust the offsets into the vertex data.

§Old path

In GLES-3.0 and WebGL2, vertex buffer layout is provided together with the actual buffer binding. We invalidate the attributes on the vertex buffer change, and re-bind them.

§New path

In GLES-3.1 and higher, the vertex buffer layout can be declared separately from the vertex data itself. This mostly matches WebGPU, however there is a catch: stride needs to be specified with the data, not as a part of the layout.

To address this, we invalidate the vertex buffers based on:

  • whether or not first_instance is used
  • stride has changed

§Handling of base_vertex, first_instance, and first_vertex

Between indirect, the lack of first_instance semantics, and the availability of gl_BaseInstance in shaders, getting buffers and builtins to work correctly is a bit tricky.

We never emulate base_vertex and gl_VertexID behaves as @builtin(vertex_index) does, so we never need to do anything about that.

§GL 4.2+ with ARB_shader_draw_parameters

  • @builtin(instance_index) translates to gl_InstanceID + gl_BaseInstance
  • We bind instance buffers without any offset emulation.
  • We advertise support for the INDIRECT_FIRST_INSTANCE feature.

While we can theoretically have a card with 4.2+ support but without ARB_shader_draw_parameters, we don’t bother with that combination.

§GLES & GL 4.1

  • @builtin(instance_index) translates to gl_InstanceID + naga_vs_first_instance
  • We bind instance buffers with offset emulation.
  • We do not advertise support for INDIRECT_FIRST_INSTANCE and cpu-side pretend the first_instance is 0 on indirect calls.

Modules§

adapter 🔒
command 🔒
conv 🔒
device 🔒
egl 🔒 Neither Windows nor webgl
cbindgen:ignore
fence 🔒
queue 🔒

Structs§

AccelerationStructure
Adapter
AdapterContextNeither Windows nor webgl
A wrapper around a [glow::Context] and the required EGL context that uses locking to guarantee exclusive access when shared with multiple threads.
AdapterContextLockNeither Windows nor webgl
A guard containing a lock to an AdapterContext, while the GL context is kept current.
AdapterShared 🔒
Api
AttributeDesc 🔒
BindGroup
BindGroupLayout
BindGroupLayoutInfo 🔒
BlendComponent 🔒
BlendDesc 🔒
Buffer
BufferBinding 🔒
ColorTargetDesc 🔒
CommandBuffer
CommandEncoder
ComputePipeline
DepthState 🔒
Device
Fence
ImageBinding 🔒
InstanceNeither Windows nor webgl
PipelineCache
PipelineInner 🔒
PipelineLayout
PrimitiveState 🔒
PrivateCapabilities 🔒
Flags that affect internal code paths but do not change the exposed feature set.
ProgramCacheKey 🔒
ProgramStage 🔒
PushConstantDesc 🔒
QuerySet
Queue
RenderPipeline
Sampler
ShaderClearProgram
ShaderModule
StencilOps 🔒
StencilSide 🔒
StencilState 🔒
SurfaceNeither Windows nor webgl
Texture
TextureFormatDesc
TextureView
VertexBufferDesc 🔒
VertexFormatDesc 🔒
Workarounds 🔒
Flags that indicate necessary workarounds for specific devices or driver bugs

Enums§

BindingRegister 🔒
Command 🔒
RawBinding 🔒
TextureInner
VertexAttribKind 🔒

Constants§

MAX_PUSH_CONSTANTS 🔒
MAX_PUSH_CONSTANT_COMMANDS 🔒
MAX_SAMPLERS 🔒
MAX_TEXTURE_SLOTS 🔒
MAX_VERTEX_ATTRIBUTES 🔒
ZERO_BUFFER_SIZE 🔒

Functions§

gl_debug_message_callback 🔒 Non-webgl
lock 🔒

Type Aliases§

BindTarget 🔒
InvalidatedAttachments 🔒
MaybeMutex 🔒
ProgramCache 🔒
SamplerBindMap 🔒
For each texture in the pipeline layout, store the index of the only sampler (in this layout) that the texture is used with.
ShaderId 🔒