hxn

GpuDevice

A GPU device on one backend, opened with GpuDevice.open. It creates resources and pipelines and runs submitted commands in order. Buffer and texture reads and writes are ordered with submissions: a write is visible to work submitted after it, and a read sees the results of work submitted before it.

features and limits say what the device can do. A call that lacks a feature throws and names the feature and the backend.

Add a driver haxelib for each backend to support, such as -lib hxn-gpu-metal -lib hxn-gpu-vulkan. Only those backends are compiled in, and open uses the first one that initializes.

Static methods

function backends():Array<Backend>

The compiled-in backends.

function defaultBackends():Array<Backend>

The compiled-in backends in the order open tries them by default. Apple platforms prefer Metal, Windows prefers Direct3D 12, other native platforms prefer Vulkan, and each falls back to Vulkan and then GLES. The browser prefers WebGPU and falls back to WebGL2.

HXN_GPU_BACKEND at run time, or -D hxn_gpu_backend at compile time, replaces this order with a comma-separated list such as vulkan,gles. The environment variable wins when both are set.

function featuresOf(backend:Backend):Features

The features of backend's devices, without opening one.

function open(?options:Null<OpenOptions>):Future<GpuDevice>

Opens a device on the first backend that has the options.required features and initializes, trying options.backends or, by default, defaultBackends() in order. If none does, the future fails with the reason for each backend.

Properties

final backend:Backend
final adapter:String

The adapter's name, as the driver reports it.

final features:Features
final limits:Limits

Methods

function createBuffer(descriptor:BufferDescriptor):Buffer
function createTexture(descriptor:TextureDescriptor):Texture
function createSampler(?descriptor:Null<SamplerDescriptor>):Sampler
function createShader(source:ShaderSource):ShaderModule

A shader from an hxnsl shader class that implements hxn.gpu.Shader: device.createShader(Tinted).

function createComputePipeline(descriptor:ComputePipelineDescriptor):ComputePipeline
function createRenderPipeline(descriptor:RenderPipelineDescriptor):RenderPipeline
function createBindGroup(descriptor:BindGroupDescriptor):BindGroup

Creates bind group group for pipeline's shader. It needs an entry for every binding the shader's LAYOUT lists in that group.

function createSurface(target:SurfaceTarget):GpuSurface

A surface presenting to target, a window or the web page's canvas. Needs Presentation.

function createCommandEncoder():CommandEncoder
function submit(encoder:CommandEncoder):Void

Runs the commands encoder recorded, after previously submitted work.

function writeBuffer(buffer:Buffer, offset:Int, bytes:Bytes):Void

Writes bytes into buffer at offset. Work submitted after this call sees the write.

function writeTexture(texture:Texture, bytes:Bytes):Void

Writes all of texture from bytes, rows top first, each width * format.bytesPerPixel() bytes long. Needs TextureWrites.

function readBuffer(buffer:Buffer, ?offset:Int = 0, ?size:Int):Future<Bytes>

Reads size bytes of buffer from offset, by default the rest of the buffer, after previously submitted work has run.

function readTexture(texture:Texture):Future<Bytes>

Reads every pixel of texture after previously submitted work has run. Rows come top first, each width * format.bytesPerPixel() bytes long.

function completed():Future<Unit>

Settles when all work submitted before this call has finished.

function close():Void

Releases the device. Close what was made from it first.