DOCSEARCHbyAlgolia
Submit Docs

wgpu-native

repository·trunk·Indexed 23 days ago

https://github.com/gfx-rs/wgpu-native

A native WebGPU implementation based on wgpu-core that provides a C-compatible API for the wgpu graphics library. It enables WebGPU capabilities in non-Rust environments, managing GPU resources such as buffers, textures, and pipelines through a centralized context. The library supports multiple backends including Vulkan, Metal, D3D12, and OpenGL, and provides bindings for languages such as Python, C++, Go, .NET, Java, and others.

Tokens
4.2K
Snippets
1
Records
38
Agent score
30%

What's inside wgpu-native

  2. Get started with wgpu-native

    trunk

    wgpu-native is a native WebGPU implementation in Rust based on wgpu-core. It provides C-language bindings for rendering and computation tasks.

    To begin using the library, refer to the Getting Started guide on the project wiki. The repository includes C-language examples that link to the native library targets to demonstrate basic rendering and computation workflows.

  3. Reference counting for wgpu resources

    trunk

    Most wgpu resources (Adapters, BindGroups, Buffers, etc.) use manual reference counting via AddRef and Release functions. To prevent memory leaks or use-after-free errors, you must call Release when you are finished with a resource.

    Common patterns:

    • wgpuAdapterAddRef / wgpuAdapterRelease
    • wgpuBindGroupAddRef / wgpuBindGroupRelease
    • wgpuBufferAddRef / wgpuBufferRelease
    • wgpuCommandBufferAddRef / wgpuCommandBufferRelease

  4. Configure and manage WGPU Surfaces

    trunk

    Surfaces are used to present rendered images to a window or screen.

    Workflow:

    1. Get Capabilities: Use wgpuSurfaceGetCapabilities to determine supported texture formats, present modes, and alpha modes for a given surface and adapter.
    2. Configure: Use wgpuSurfaceConfigure with a WGPUSurfaceConfiguration to set the surface's usage, format, and dimensions.
    3. Get Texture: Use wgpuSurfaceGetCurrentTexture to retrieve the next available texture for rendering. This returns a status (e.g., SuccessOptimal, Suboptimal, Timeout, Outdated, Lost, Occluded, or Error).
    4. Present: After rendering to the texture, call wgpuSurfacePresent to submit the texture to the display.
    5. Unconfigure: Use wgpuSurfaceUnconfigure to release surface-specific data when the configuration changes or the surface is no longer needed.

  5. Identify available wgpu-native language bindings

    trunk

    wgpu-native provides bindings for a wide variety of languages. Common wrappers include:

    • Rust: gfx-rs/wgpu-rs (idiomatic wrapper)
    • Python: pygfx/wgpu-py
    • C++: WebGPU-C++ (auto-generated)
    • Go: go-webgpu/webgpu (Zero-CGO)
    • .NET: trivaxy/wgpu.NET, dotnet/Silk.NET, or Alimer.Bindings.WebGPU
    • Java/Kotlin: kgpu/wgpuj, wgpu4k/wgpu4k, or vulkan4j
    • Other: Crystal (wgpu.cr), D (bindc-wgpu), Julia (WebGPU.jl), Zig (wgpu_native_zig), and Mojo (wgpu-mojo).

  7. Free SurfaceCapabilities members

    trunk
    When you receive a WGPUSurfaceCapabilities struct from wgpuSurfaceGetCapabilities, it contains pointers to arrays for formats, presentModes, and alphaModes. You must call wgpuSurfaceCapabilitiesFreeMembers to properly release the memory allocated for these arrays to avoid leaks.

  8. Record commands with WGPUCommandEncoder

    trunk

    The WGPUCommandEncoder provides several methods to record GPU operations:

    • Buffer Operations:

      • wgpuCommandEncoderClearBuffer: Clears a range of a buffer.
      • wgpuCommandEncoderCopyBufferToBuffer: Copies data from one buffer to another.
      • wgpuCommandEncoderCopyBufferToTexture: Copies data from a buffer to a texture.
      • wgpuCommandEncoderCopyTextureToBuffer: Copies data from a texture to a buffer.
      • wgpuCommandEncoderCopyTextureToTexture: Copies data from one texture to another.

    • Texture Operations:

      • wgpuCommandEncoderClearTexture: Clears a specific subresource range of a texture.

    • Query Operations:

      • wgpuCommandEncoderResolveQuerySet: Resolves query results into a buffer.
      • wgpuCommandEncoderWriteTimestamp: Writes a timestamp to a query set.

    • Debugging:

      • wgpuCommandEncoderInsertDebugMarker: Inserts a single debug marker.
      • wgpuCommandEncoderPushDebugGroup: Starts a debug group.
      • wgpuCommandEncoderPopDebugGroup: Ends the current debug group.

  9. Create a Shader Module with wgpuDeviceCreateShaderModule

    trunk

    Use wgpuDeviceCreateShaderModule to create a shader module from source code (SPIR-V, WGSL, or GLSL).

    There is also a wgpuDeviceCreateShaderModuleTrusted variant that allows specifying WGPUShaderRuntimeChecks for more control over runtime validation.

  10. Manage Device Lifecycle and Capabilities

    trunk

    The WGPUDevice interface provides methods to query capabilities and manage the device state:

    • wgpuDeviceGetFeatures: Retrieves the supported features of the device. Returns WGPUStatus_Success on success.
    • wgpuDeviceGetLimits: Fills a provided WGPULimits struct with the device's limits.
    • wgpuDeviceHasFeature: Checks if a specific WGPUFeatureName is supported.
    • wgpuDeviceDestroy: Destroys the device.
    • wgpuDeviceAddRef / wgpuDeviceRelease: Manually manage the reference count of the device.

  11. Get instance limits with wgpuGetInstanceLimits

    trunk

    Retrieve the capabilities and limits of the wgpu instance. Pass a pointer to a WGPUInstanceLimits struct to be populated.

    Note: timedWaitAnyMaxCount is currently set to 0 by this implementation.

  12. Manage WGPUTexture lifecycle and properties

    trunk
    Use the following functions to manage the lifecycle and query properties of a WGPUTexture. Note that wgpuTextureDestroy can be called multiple times safely without error. For manual memory management in C-style bindings, use wgpuTextureAddRef and wgpuTextureRelease to increment or decrement the reference count.