Interface WgpuBindings

All Known Implementing Classes:
TracingWgpuBindings
public interface WgpuBindings
Abstraction over WebGPU native bindings.

All WebGPU objects are represented as opaque long handles. Implementations convert between these handles and their concrete wrapper types (e.g. jWebGPU's WGPUDevice).

The interface mirrors the WebGPU API at a level of abstraction suitable for the engine's render device. Descriptor-heavy WebGPU calls are flattened into method parameters to avoid leaking provider-specific descriptor types.

  • Field Details

  • Method Details

    • initialize

      boolean initialize()
      Initializes the WebGPU loader/library. Returns true if successful.

    • isAvailable

      boolean isAvailable()
      Returns true if the native WebGPU library is available.

    • configureSurface

      default long configureSurface(long instance, long device, WindowHandle window)
      Configures a presentation surface for the given window. Desktop: creates a wgpu surface using WindowHandle.surfaceInfo(). Web: configures the canvas context. Returns a surface/context handle, or 0 if not supported (headless).

    • getSurfaceTextureView

      default long getSurfaceTextureView(long surface)
      Gets the current surface texture view for rendering. Returns 0 if no surface is configured (offscreen/headless).

    • releaseSurfaceTextureView

      default void releaseSurfaceTextureView(long textureView)
      Releases a surface texture view obtained from getSurfaceTextureView.

    • surfacePresent

      default void surfacePresent(long surface)
      Presents the current surface texture to the screen. Desktop: calls wgpuSurfacePresent. Web: no-op (browser presents after submit).

    • surfaceFormat

      default int surfaceFormat()
      Returns the texture format used by the presentation surface. Defaults to BGRA8 (desktop wgpu-native). Web browsers may use RGBA8.

    • hasSurface

      default boolean hasSurface()
      Returns true if a presentation surface is available.

    • setPresentMode

      default void setPresentMode(int mode)
      Sets the present mode for surface configuration. Must be called before configureSurface.

    • createInstance

      long createInstance()
      Creates a WebGPU instance.

    • instanceProcessEvents

      void instanceProcessEvents(long instance)
      Processes pending events on the instance.

    • instanceRelease

      void instanceRelease(long instance)
      Releases the instance.

    • instanceRequestAdapter

      long instanceRequestAdapter(long instance)
      Requests an adapter from the instance (synchronous). Returns the adapter handle, or 0 on failure.

    • adapterRelease

      void adapterRelease(long adapter)
      Releases the adapter.

    • adapterRequestDevice

      long adapterRequestDevice(long instance, long adapter)
      Requests a device from the adapter (synchronous). Requires the instance handle for event processing. Returns the device handle, or 0 on failure.

    • deviceGetQueue

      long deviceGetQueue(long device)
      Gets the device's queue.

    • deviceRelease

      void deviceRelease(long device)
      Releases the device.

    • deviceGetLimits

      default WgpuBindings.DeviceLimits deviceGetLimits(long device)
      Queries device limits. Returns null if not supported.

    • deviceCreateBuffer

      long deviceCreateBuffer(long device, long size, int usage)
      Creates a GPU buffer.
      Parameters:
      device - the device handle
      size - buffer size in bytes
      usage - combined WebGPU buffer usage flags
      Returns:
      buffer handle

    • bufferRelease

      void bufferRelease(long buffer)
      Releases a buffer.

    • queueWriteBuffer

      void queueWriteBuffer(long queue, long buffer, int offset, ByteBuffer data, int size)
      Writes data to a buffer via the queue.
      Parameters:
      queue - the queue handle
      buffer - the destination buffer handle
      offset - byte offset into the buffer
      data - direct ByteBuffer with data to write
      size - number of bytes to write

    • bufferMapReadSync

      void bufferMapReadSync(long instance, long buffer, int size, int maxPolls)
      Maps a buffer for reading (synchronous, polls instance events).
      Parameters:
      instance - the instance handle (for event polling)
      buffer - the buffer handle
      size - number of bytes to map
      maxPolls - maximum number of event poll iterations

    • bufferGetConstMappedRange

      void bufferGetConstMappedRange(long buffer, int offset, int size, ByteBuffer dest)
      Gets the mapped range of a buffer into the provided direct ByteBuffer.

    • bufferUnmap

      void bufferUnmap(long buffer)
      Unmaps a previously mapped buffer.

    • deviceCreateTexture

      long deviceCreateTexture(long device, int width, int height, int depthOrLayers, int format, int dimension, int usage)
      Creates a texture.
      Parameters:
      device - the device handle
      width - texture width
      height - texture height
      depthOrLayers - depth (for 3D) or array layers
      format - WebGPU texture format ordinal (from
      invalid reference 
      WgpuTextureFormat
      )
      dimension - 0 = 2D, 1 = 3D
      usage - combined WebGPU texture usage flags
      Returns:
      texture handle

    • textureCreateView

      long textureCreateView(long texture, int format, int viewDimension, int arrayLayerCount)
      Creates a texture view.
      Parameters:
      texture - the texture handle
      format - WebGPU texture format ordinal
      viewDimension - view dimension ordinal (from
      invalid reference 
      WgpuTextureViewDimension
      )
      arrayLayerCount - number of array layers
      Returns:
      texture view handle

    • textureRelease

      void textureRelease(long texture)
      Releases a texture.

    • textureViewRelease

      void textureViewRelease(long textureView)
      Releases a texture view.

    • queueWriteTexture

      void queueWriteTexture(long queue, long texture, int width, int height, int depthOrLayers, int bytesPerRow, ByteBuffer data)
      Writes pixel data to a texture via the queue.
      Parameters:
      queue - the queue handle
      texture - the destination texture handle
      width - write region width
      height - write region height
      depthOrLayers - write region depth/layers
      bytesPerRow - bytes per row in the source data
      data - direct ByteBuffer with pixel data

    • deviceCreateSampler

      long deviceCreateSampler(long device, int addressU, int addressV, int addressW, int magFilter, int minFilter, int mipmapFilter, float lodMinClamp, float lodMaxClamp, int compare, float maxAnisotropy)
      Creates a sampler.
      Parameters:
      device - the device handle
      addressU - address mode U ordinal (from
      invalid reference 
      WgpuAddressMode
      )
      addressV - address mode V ordinal
      addressW - address mode W ordinal
      magFilter - mag filter ordinal (from
      invalid reference 
      WgpuFilterMode
      )
      minFilter - min filter ordinal
      mipmapFilter - mipmap filter ordinal (from
      invalid reference 
      WgpuMipmapFilterMode
      )
      Returns:
      sampler handle

    • samplerRelease

      void samplerRelease(long sampler)
      Releases a sampler.

    • deviceCreateShaderModule

      long deviceCreateShaderModule(long device, String wgsl)
      Creates a shader module from WGSL source.
      Parameters:
      device - the device handle
      wgsl - WGSL shader source code
      Returns:
      shader module handle, or 0 if creation failed

    • shaderModuleIsValid

      boolean shaderModuleIsValid(long shaderModule)
      Returns true if the shader module handle is valid.

    • shaderModuleRelease

      void shaderModuleRelease(long shaderModule)
      Releases a shader module.

    • deviceCreateBindGroupLayout

      long deviceCreateBindGroupLayout(long device, WgpuBindings.BindGroupLayoutEntry[] entries)
      Creates a bind group layout with the given entries.
      Parameters:
      device - the device handle
      entries - array of WgpuBindings.BindGroupLayoutEntry descriptors
      Returns:
      bind group layout handle

    • bindGroupLayoutRelease

      void bindGroupLayoutRelease(long bindGroupLayout)
      Releases a bind group layout.

    • deviceCreatePipelineLayout

      long deviceCreatePipelineLayout(long device, long[] bindGroupLayouts)
      Creates a pipeline layout from bind group layouts.
      Parameters:
      device - the device handle
      bindGroupLayouts - array of bind group layout handles
      Returns:
      pipeline layout handle

    • pipelineLayoutRelease

      void pipelineLayoutRelease(long pipelineLayout)
      Releases a pipeline layout.

    • deviceCreateRenderPipeline

      long deviceCreateRenderPipeline(long device, WgpuBindings.RenderPipelineDescriptor desc)
      Creates a render pipeline.
      Parameters:
      device - the device handle
      desc - the pipeline descriptor
      Returns:
      render pipeline handle

    • renderPipelineRelease

      void renderPipelineRelease(long renderPipeline)
      Releases a render pipeline.

    • deviceCreateBindGroup

      long deviceCreateBindGroup(long device, long layout, WgpuBindings.BindGroupEntry[] entries)
      Creates a bind group.
      Parameters:
      device - the device handle
      layout - the bind group layout handle
      entries - array of bind group entry descriptors
      Returns:
      bind group handle

    • bindGroupRelease

      void bindGroupRelease(long bindGroup)
      Releases a bind group.

    • deviceCreateCommandEncoder

      long deviceCreateCommandEncoder(long device)
      Creates a command encoder.

    • commandEncoderBeginRenderPass

      long commandEncoderBeginRenderPass(long encoder, WgpuBindings.RenderPassDescriptor desc)
      Begins a render pass on the command encoder.
      Parameters:
      encoder - the command encoder handle
      desc - the render pass descriptor
      Returns:
      render pass encoder handle

    • commandEncoderCopyBufferToBuffer

      void commandEncoderCopyBufferToBuffer(long encoder, long src, int srcOffset, long dst, int dstOffset, int size)
      Copies data between buffers.

    • commandEncoderCopyTextureToBuffer

      void commandEncoderCopyTextureToBuffer(long encoder, long texture, long buffer, int width, int height, int bytesPerRow, int rowsPerImage)
      Copies a texture to a buffer.

    • commandEncoderFinish

      long commandEncoderFinish(long encoder)
      Finishes the command encoder, producing a command buffer.
      Parameters:
      encoder - the command encoder handle
      Returns:
      command buffer handle

    • commandEncoderRelease

      void commandEncoderRelease(long encoder)
      Releases a command encoder.

    • commandBufferRelease

      void commandBufferRelease(long commandBuffer)
      Releases a command buffer.

    • queueSubmit

      void queueSubmit(long queue, long commandBuffer)
      Submits a command buffer to the queue.

    • renderPassEnd

      void renderPassEnd(long renderPass)
      Ends the render pass.

    • renderPassRelease

      void renderPassRelease(long renderPass)
      Releases the render pass encoder.

    • renderPassSetPipeline

      void renderPassSetPipeline(long renderPass, long pipeline)
      Sets the pipeline on the render pass.

    • renderPassSetVertexBuffer

      void renderPassSetVertexBuffer(long renderPass, int slot, long buffer, int offset, int size)
      Sets a vertex buffer on the render pass.

    • renderPassSetIndexBuffer

      void renderPassSetIndexBuffer(long renderPass, long buffer, int indexFormat, int offset, int size)
      Sets the index buffer on the render pass.

    • renderPassSetBindGroup

      void renderPassSetBindGroup(long renderPass, int groupIndex, long bindGroup)
      Sets the bind group on the render pass.

    • renderPassSetViewport

      void renderPassSetViewport(long renderPass, float x, float y, float w, float h, float minDepth, float maxDepth)
      Sets the viewport on the render pass.

    • renderPassSetScissorRect

      void renderPassSetScissorRect(long renderPass, int x, int y, int width, int height)
      Sets the scissor rect on the render pass.

    • renderPassSetStencilReference

      void renderPassSetStencilReference(long renderPass, int ref)
      Sets the stencil reference on the render pass.

    • renderPassDraw

      void renderPassDraw(long renderPass, int vertexCount, int instanceCount, int firstVertex, int firstInstance)
      Draws primitives.

    • renderPassDrawIndexed

      void renderPassDrawIndexed(long renderPass, int indexCount, int instanceCount, int firstIndex, int baseVertex, int firstInstance)
      Draws indexed primitives.