GLGraphicsDriver

View source
clay.opengl.GLGraphicsDriver (Class)

OpenGL implementation of the cross-platform graphics driver interface.

This class provides instance methods for GPU resource management including textures, shaders, render targets, and framebuffer operations. It serves as the OpenGL backend for Clay's graphics abstraction layer.

The API is designed to be cross-platform, allowing other graphics backends (D3D12, Metal, Vulkan) to implement equivalent functionality via spec.GraphicsDriver.

Key features:

  • Texture creation, binding, and management
  • Shader compilation and uniform management
  • Render target creation for off-screen rendering
  • Framebuffer and renderbuffer management
  • Blending and viewport configuration

Access via Clay.app.graphics.

Instance Members

noTexture: clay.TextureId

Sentinel value representing no texture bound.

noFramebuffer: clay.Framebuffer

Sentinel value representing the default framebuffer.

noRenderbuffer: clay.Renderbuffer

Sentinel value representing the default renderbuffer.

Sentinel value representing no shader handle.

Sentinel value representing no program handle.

Sentinel value representing an invalid uniform location.

Sentinel value representing no buffer bound.

setup(): Void

Initializes the graphics driver after the graphics context is ready.

This must be called once after the window and graphics context are created. Fetches default framebuffer and renderbuffer bindings from the platform.

getMaxTextureSize(): Int

Returns the maximum texture size supported by the GPU.

Returns Description
Int Maximum texture dimension in pixels
getMaxTextureUnits(): Int

Returns the maximum number of texture units available.

Returns Description
Int Maximum number of texture units (capped at 32)
testShaderCompilationLimit(?maxIfs: Int = 32): Int

Tests the maximum number of if-statements supported in fragment shaders.

This is used for multi-texture batching optimization, which requires conditional texture sampling based on texture ID per vertex.

Name Type Default Description
maxIfs Int 32 Starting maximum to test (halves on failure until working)
Returns Description
Int Maximum number of if-statements supported
loadExtensions(): Void

Loads platform-specific graphics extensions.

On WebGL, this loads extensions like OES_standard_derivatives that provide additional shader functionality.

readPixels(x: Int, y: Int, width: Int, height: Int, pixels: clay.buffers.Uint8Array): Void

Reads pixels from the current framebuffer.

The pixels are read in RGBA format with unsigned bytes (0-255). The buffer must be large enough to hold width * height * 4 bytes.

Name Type Description
x Int X position to start reading
y Int Y position to start reading
width Int Width of the rectangle to read
height Int Height of the rectangle to read
pixels clay.buffers.Uint8Array Buffer to store RGBA pixel data
clear(r: Float, g: Float, b: Float, a: Float, ?clearDepth: Bool = true): Void

Clears the current render buffer.

Name Type Default Description
r Float Red component of clear color (0.0 to 1.0)
g Float Green component of clear color (0.0 to 1.0)
b Float Blue component of clear color (0.0 to 1.0)
a Float Alpha component of clear color (0.0 to 1.0)
clearDepth Bool true Whether to also clear the depth buffer (default: true)
setViewport(x: Int, y: Int, width: Int, height: Int): Void

Sets the viewport dimensions.

Name Type Description
x Int Left edge of viewport
y Int Bottom edge of viewport
width Int Viewport width in pixels
height Int Viewport height in pixels
enableBlending(): Void

Enables alpha blending for subsequent draw operations.

disableBlending(): Void

Disables alpha blending for subsequent draw operations.

setBlendFuncSeparate(srcRgb: clay.BlendMode, dstRgb: clay.BlendMode, srcAlpha: clay.BlendMode, dstAlpha: clay.BlendMode): Void

Sets separate blend functions for RGB and alpha channels.

Name Type Description
srcRgb clay.BlendMode Source blend factor for RGB channels
dstRgb clay.BlendMode Destination blend factor for RGB channels
srcAlpha clay.BlendMode Source blend factor for alpha channel
dstAlpha clay.BlendMode Destination blend factor for alpha channel
createTextureId(): clay.TextureId

Creates a new texture and returns its identifier.

Returns Description
clay.TextureId New texture identifier
deleteTexture(textureId: clay.TextureId): Void

Deletes a texture from the GPU.

Name Type Description
textureId clay.TextureId Texture identifier to delete
setActiveTexture(slot: Int): Void

Sets the active texture slot for subsequent texture operations.

Name Type Description
slot Int Texture slot index (0-based)
bindTexture2d(textureId: clay.TextureId): Void

Binds a 2D texture to the current texture slot.

Name Type Description
textureId clay.TextureId Texture identifier to bind, or noTexture to unbind
maxTextureSize(): Int

Returns the maximum texture size supported by the GPU.

Returns Description
Int Maximum texture dimension in pixels
needsPreprocessedPremultipliedAlpha(): Bool

Checks if premultiplied textures require pixel preprocessing.

Returns Description
Bool True if preprocessing is needed, false if handled by GL
submitTexture2dPixels(level: Int, format: clay.TextureFormat, width: Int, height: Int, dataType: clay.TextureDataType, pixels: clay.buffers.Uint8Array, premultipliedAlpha: Bool): Void

Submits 2D texture pixels to the GPU.

Name Type Description
level Int Mipmap level (0 = base image)
format clay.TextureFormat Texture format (RGB or RGBA)
width Int Texture width in pixels
height Int Texture height in pixels
dataType clay.TextureDataType Data type of pixel data (UNSIGNED_BYTE)
pixels clay.buffers.Uint8Array Pixel data buffer
premultipliedAlpha Bool Whether pixels use premultiplied alpha
submitCompressedTexture2dPixels(level: Int, format: clay.TextureFormat, width: Int, height: Int, pixels: clay.buffers.Uint8Array, premultipliedAlpha: Bool): Void

Submits compressed 2D texture pixels to the GPU.

Name Type Description
level Int Mipmap level (0 = base image)
format clay.TextureFormat Compressed texture format
width Int Texture width in pixels
height Int Texture height in pixels
pixels clay.buffers.Uint8Array Compressed pixel data buffer
premultipliedAlpha Bool Whether pixels use premultiplied alpha
fetchTexture2dPixels(into: clay.buffers.Uint8Array, x: Int, y: Int, w: Int, h: Int): Void

Fetches 2D texture pixels from the GPU.

Name Type Description
into clay.buffers.Uint8Array Buffer to store pixel data (must be at least w * h * 4 bytes)
x Int X position of texture rectangle to fetch
y Int Y position of texture rectangle to fetch
w Int Width of texture rectangle to fetch
h Int Height of texture rectangle to fetch
setTexture2dMinFilter(minFilter: clay.TextureFilter): Void

Sets the minification filter for 2D textures.

Name Type Description
minFilter clay.TextureFilter Filter mode (NEAREST, LINEAR, or mipmap variants)
setTexture2dMagFilter(magFilter: clay.TextureFilter): Void

Sets the magnification filter for 2D textures.

Name Type Description
magFilter clay.TextureFilter Filter mode (NEAREST or LINEAR)
setTexture2dWrapS(wrapS: clay.TextureWrap): Void

Sets the horizontal (S) texture wrap mode.

Name Type Description
wrapS clay.TextureWrap Wrap mode (CLAMP_TO_EDGE, REPEAT, or MIRRORED_REPEAT)
setTexture2dWrapT(wrapT: clay.TextureWrap): Void

Sets the vertical (T) texture wrap mode.

Name Type Description
wrapT clay.TextureWrap Wrap mode (CLAMP_TO_EDGE, REPEAT, or MIRRORED_REPEAT)
createFramebuffer(): clay.Framebuffer

Creates a new framebuffer object.

Returns Description
clay.Framebuffer Created framebuffer
bindFramebuffer(framebuffer: clay.Framebuffer): Void

Binds a framebuffer for rendering.

Name Type Description
framebuffer clay.Framebuffer Framebuffer to bind, or noFramebuffer for default
createRenderbuffer(): clay.Renderbuffer

Creates a new renderbuffer object.

Returns Description
clay.Renderbuffer Created renderbuffer
bindRenderbuffer(renderbuffer: clay.Renderbuffer): Void

Binds a renderbuffer.

Name Type Description
renderbuffer clay.Renderbuffer Renderbuffer to bind, or noRenderbuffer for default
createRenderTarget(textureId: clay.TextureId, width: Int, height: Int, depth: Bool, stencil: Bool, antialiasing: Int, level: Int, format: clay.TextureFormat, dataType: clay.TextureDataType): clay.RenderTarget

Creates a render target for off-screen rendering.

Name Type Description
textureId clay.TextureId Texture to render into
width Int Render target width in pixels
height Int Render target height in pixels
depth Bool Whether to include a depth buffer
stencil Bool Whether to include a stencil buffer
antialiasing Int MSAA sample count (0 or 1 for none)
level Int Mipmap level (0 = base)
format clay.TextureFormat Texture format
dataType clay.TextureDataType Data type of texture
Returns Description
clay.RenderTarget Created render target
deleteRenderTarget(renderTarget: clay.RenderTarget): Void

Deletes a render target from the GPU.

Name Type Description
renderTarget clay.RenderTarget Render target to delete
setRenderTarget(renderTarget: clay.RenderTarget): Void

Sets the render target for subsequent draw operations.

Name Type Description
renderTarget clay.RenderTarget Render target to draw into, or null for main framebuffer
configureRenderTargetBuffersStorage(renderTarget: clay.RenderTarget, textureId: clay.TextureId, width: Int, height: Int, depth: Bool, stencil: Bool, antialiasing: Int): Void

Configures storage for render target buffers.

Used when resizing a render target's underlying buffers.

Name Type Description
renderTarget clay.RenderTarget Render target to configure
textureId clay.TextureId Texture associated with the render target
width Int New width in pixels
height Int New height in pixels
depth Bool Whether to include depth buffer
stencil Bool Whether to include stencil buffer
antialiasing Int MSAA sample count
blitRenderTargetBuffers(renderTarget: clay.RenderTarget, width: Int, height: Int): Void

Resolves MSAA render target buffers to the texture.

Called when switching away from an antialiased render target to blit the multisampled content to the texture.

Name Type Description
renderTarget clay.RenderTarget Render target to resolve
width Int Width of the render target
height Int Height of the render target
createShader(vertSource: String, fragSource: String, ?attributes: Array<String>, ?textures: Array<String>): clay.GpuShader

Creates and compiles a shader program.

Automatically patches GLSL version for platform compatibility:

  • Desktop GL (non-ANGLE): converts #version 300 es to #version 330
  • Mobile/WebGL (GLES/ANGLE): keeps #version 300 es
Name Type Default Description
vertSource String Vertex shader source code
fragSource String Fragment shader source code
attributes Array<String> (optional) Optional array of attribute names in binding order
textures Array<String> (optional) Optional array of texture uniform names in slot order
Returns Description
clay.GpuShader Compiled shader, or null on failure
deleteShader(shader: clay.GpuShader): Void

Deletes a shader program from the GPU.

Name Type Description
shader clay.GpuShader Shader program to delete
useShader(shader: clay.GpuShader): Void

Activates a shader program for subsequent draw operations.

Name Type Description
shader clay.GpuShader Shader program to use
synchronizeShaderMatrices(shader: clay.GpuShader): Void

Synchronizes projectionMatrix and modelViewMatrix with the given shader, as this is needed on some graphics backend.

Name Type Description
shader clay.GpuShader Shader program to synchronize
getUniformLocation(shader: clay.GpuShader, name: String): clay.UniformLocation

Gets the location of a uniform variable in a shader.

Name Type Description
shader clay.GpuShader Shader program
name String Uniform variable name
Returns Description
clay.UniformLocation Uniform location, or noLocation if not found
setIntUniform(shader: clay.GpuShader, location: clay.UniformLocation, value: Int): Void

Sets an integer uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value Int Integer value
setIntArrayUniform(shader: clay.GpuShader, location: clay.UniformLocation, value: clay.buffers.Int32Array): Void

Sets an integer array uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value clay.buffers.Int32Array Integer array
setFloatUniform(shader: clay.GpuShader, location: clay.UniformLocation, value: Float): Void

Sets a float uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value Float Float value
setFloatArrayUniform(shader: clay.GpuShader, location: clay.UniformLocation, value: clay.buffers.Float32Array): Void

Sets a float array uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value clay.buffers.Float32Array Float array
setVector2Uniform(shader: clay.GpuShader, location: clay.UniformLocation, x: Float, y: Float): Void

Sets a 2D vector uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
x Float X component
y Float Y component
setVector3Uniform(shader: clay.GpuShader, location: clay.UniformLocation, x: Float, y: Float, z: Float): Void

Sets a 3D vector uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
x Float X component
y Float Y component
z Float Z component
setVector4Uniform(shader: clay.GpuShader, location: clay.UniformLocation, x: Float, y: Float, z: Float, w: Float): Void

Sets a 4D vector uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
x Float X component
y Float Y component
z Float Z component
w Float W component
setMatrix2Uniform(shader: clay.GpuShader, location: clay.UniformLocation, value: clay.buffers.Float32Array): Void

Sets a 2x2 matrix uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value clay.buffers.Float32Array Matrix as Float32Array (4 elements, column-major)
setMatrix3Uniform(shader: clay.GpuShader, location: clay.UniformLocation, value: clay.buffers.Float32Array): Void

Sets a 3x3 matrix uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value clay.buffers.Float32Array Matrix as Float32Array (9 elements, column-major)
setMatrix4Uniform(shader: clay.GpuShader, location: clay.UniformLocation, value: clay.buffers.Float32Array): Void

Sets a 4x4 matrix uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
value clay.buffers.Float32Array Matrix as Float32Array (16 elements, column-major)
setTexture2dUniform(shader: clay.GpuShader, location: clay.UniformLocation, slot: Int, texture: clay.TextureId): Void

Sets a texture sampler uniform value.

Name Type Description
shader clay.GpuShader Shader program
location clay.UniformLocation Uniform location
slot Int Texture slot index
texture clay.TextureId Texture identifier to bind
ensureNoError(): Void

Checks for and throws on any pending graphics errors.

Useful for debugging graphics operations.

new(): Void

Creates a new OpenGL graphics driver instance.

Private Members

DEPTH24_STENCIL8: Int
DEPTH_COMPONENT24: Int
TEXTURE_2D_MULTISAMPLE: Int
READ_FRAMEBUFFER: Int
DRAW_FRAMEBUFFER: Int
RGBA8: Int
COLOR: Int
projectionMatrix: clay.buffers.Float32Array
patchGlslVersion(source: String): String

Patches GLSL version directive for platform compatibility.

Shade compiler outputs GLES 3.0 syntax (#version 300 es). Desktop GL (non-ANGLE) requires #version 330 instead.

Name Type Description
source String Shader source code
Returns Description
String Patched source code
linkShader(shader: GLGraphicsDriver_GpuShader, ?attributes: Array<String>): Bool

Links vertex and fragment shaders into a program.

Name Type Default Description
shader GLGraphicsDriver_GpuShader Shader object with compiled vert/frag shaders
attributes Array<String> (optional) Optional array of attribute names in binding order
Returns Description
Bool True if linking succeeded, false otherwise
configureShaderTextureSlots(shader: GLGraphicsDriver_GpuShader, textures: Array<String>): Void

Configures texture slot uniform bindings for a shader.

Name Type Description
shader GLGraphicsDriver_GpuShader Shader to configure
textures Array<String> Array of texture uniform names in slot order
compileGLShader(type: Int, source: String): GLShader

Compiles a single GL shader (vertex or fragment).

Name Type Description
type Int GL.VERTEX_SHADER or GL.FRAGMENT_SHADER
source String GLSL source code
Returns Description
GLShader Compiled shader, or noShader on failure