#Milky2018/wgpu_mbt

#Supported Platforms

#Install

1. Add dependency:

{
  "import": [
    { "path": "Milky2018/wgpu_mbt", "alias": "wgpu" }
  ]
}

2. Choose a link mode:

• Static (default): no extra downstream link flags; the prebuild hook downloads and links a verified upstream static archive automatically
• Dynamic: set MBT_WGPU_LINK_MODE=dynamic before moon build / moon test, then extract a matching upstream release archive

3. Dynamic mode uses the official upstream release assets:

• https://github.com/gfx-rs/wgpu-native/releases/tag/v27.0.4.0

• macOS: $HOME/.local/lib/libwgpu_native.dylib
• Linux: $HOME/.local/lib/libwgpu_native.so
• Windows: %USERPROFILE%\\.local\\lib\\wgpu_native.dll
• metadata tag: .../wgpu-native-meta/wgpu-native-git-tag

#Quick Example

fn main {
  try {
    let instance = @wgpu.Instance::create()
    let adapter = instance.request_adapter_sync()
    let device = adapter.request_device_sync(instance)
    let queue = device.queue()

    let buf = device.create_buffer(
      size=4UL,
      usage=@wgpu.BufferUsage::from_u64(@wgpu.BUFFER_USAGE_COPY_DST),
    )
    ignore(buf.size())

    let shader = device.create_shader_module_wgsl(
      #|@compute @workgroup_size(1)
      #|fn main() {}
      #|,
    )
    let pipeline = device.create_compute_pipeline(shader)
    let encoder = device.create_command_encoder()
    let pass = encoder.begin_compute_pass()
    pass.set_pipeline(pipeline)
    pass.dispatch_workgroups(1U, 1U, 1U)
    pass.end()
    pass.release()

    let cmd = encoder.finish()
    queue.submit_one(cmd)

    cmd.release()
    encoder.release()
    pipeline.release()
    shader.release()
    buf.release()
    queue.release()
    device.release()
    adapter.release()
    instance.release()
  } catch {
    e => println(e.message())
  }
}

#Surface Configuration (Frame Latency)

let config = @wgpu.SurfaceConfiguration::new(
  width,
  height,
  usage,
  format,
  @wgpu.PresentMode::from_u32(present_mode_u32),
  @wgpu.CompositeAlphaMode::from_u32(alpha_mode_u32),
)
  .with_view_formats([format])
  .with_desired_maximum_frame_latency(2U)

surface.configure_with_or_raise(adapter, device, config)

• surface_configuration_ptr_new(device, config)
• surface_configuration_ptr_free(config_ptr)

#Surface Sources (All Common Native Sources)

• Metal: Instance::create_surface_metal_layer()
• Wayland: Instance::create_surface_wayland(display, surface)
• XCB: Instance::create_surface_xcb(connection, window)
• Xlib: Instance::create_surface_xlib(display, window)
• Windows HWND: Instance::create_surface_windows_hwnd(hinstance, hwnd)
• Windows SwapChainPanel: Instance::create_surface_swap_chain_panel(panel_native)
• Android: Instance::create_surface_android_native_window(window)

• surface_descriptor_metal_layer_new
• surface_descriptor_wayland_new
• surface_descriptor_xcb_new
• surface_descriptor_xlib_new
• surface_descriptor_windows_hwnd_new
• surface_descriptor_swap_chain_panel_new
• surface_descriptor_android_native_window_new
• surface_descriptor_free

#Native Instance Extras

• Instance::create_with_extras_u32(backends_u64, flags_u32, dx12_shader_compiler_u32, gles3_minor_version_u32, gl_fence_behaviour_u32, dxc_max_shader_model_u32, dx12_presentation_system_u32, dxc_path)

• @wgpu_c.device_descriptor_set_trace_path_utf8(desc, trace_path, trace_path_len)

#Shader / Pipeline Native Extras

• GLSL shader module descriptor and helper:
  • @wgpu_c.shader_module_descriptor_glsl_new(stage_u64, code, code_len)
  • Device::create_shader_module_glsl(stage_u64, code)
• Query set descriptor extras with multiple pipeline statistics:
  • @wgpu_c.query_set_descriptor_pipeline_statistics_many_new(...)
  • Device::create_query_set_pipeline_statistics_many(count, first_statistic_name_u32, other_statistic_names_u32)
• Pipeline layout extras with multiple push-constant ranges:
  • @wgpu_c.pipeline_layout_descriptor_push_constants_many_new(...)
  • Device::create_pipeline_layout_push_constants_many(first_stages, first_start, first_end, other_ranges)
• Render pipeline primitive extras on builder:
  • RenderPipelineDescBuilder::set_polygon_mode_u32(...)
  • RenderPipelineDescBuilder::set_conservative_rasterization(...)
  • RenderPipelineDescBuilder::clear_primitive_extras()

#Async Future APIs

• Adapter request:
  • Instance::request_adapter_future_id_u64(...)
  • Instance::request_adapter_async_status_u32(...)
  • Instance::request_adapter_async_take_or_raise(...)
• Device request:
  • Adapter::request_device_future_id_u64(...)
  • Adapter::request_device_async_status_u32(...)
  • Adapter::request_device_async_take_or_raise(...)

#Runtime Behavior

• Static mode is the default and links the verified upstream static library into the final native binary.
• Dynamic mode is opt-in and loads libwgpu_native at runtime.
• Dynamic library lookup order:
  1. MBT_WGPU_NATIVE_LIB
  2. default per-user path listed above
• @wgpu.native_available() checks whether the core library/symbols are loadable.
• @wgpu.native_supported() checks whether the current runtime matches the supported upstream release.
• @wgpu.native_static_linked() reports whether this build used static linking.
• @wgpu.native_expected_release_tag() returns the supported upstream release tag.
• @wgpu.native_diagnostic() returns a combined loader/support diagnostic string.
• For custom dynamic builds without release metadata, set MBT_WGPU_NATIVE_ALLOW_UNVERIFIED=1 to bypass strict release verification.
• To force dynamic mode in a downstream project, export MBT_WGPU_LINK_MODE=dynamic for moon check / moon build / moon test.

#Optional Feature Gates

• Debug labels / markers are off by default
  • enable via @wgpu.set_debug_labels_enabled(true) or MBT_WGPU_DEBUG_LABELS=1
• Async pipeline creation is off by default
  • enable via MBT_WGPU_ENABLE_PIPELINE_ASYNC=1 or @wgpu.set_pipeline_async_enabled(true)
  • probe via @wgpu.pipeline_async_enabled() / @wgpu.pipeline_async_available()
• Shader compilation info is off by default
  • enable via MBT_WGPU_ENABLE_COMPILATION_INFO=1 or @wgpu.set_compilation_info_enabled(true)
  • probe via @wgpu.compilation_info_enabled() / @wgpu.compilation_info_available()
• Native features:
  • clear texture: @wgpu.NATIVE_FEATURE_CLEAR_TEXTURE
  • multiview: @wgpu.NATIVE_FEATURE_MULTIVIEW
  • quick checks: Adapter::has_feature_native_clear_texture() / Adapter::has_feature_native_multiview()
• Force-disable env vars always take precedence:
  • MBT_WGPU_DISABLE_PIPELINE_ASYNC=1
  • MBT_WGPU_DISABLE_COMPILATION_INFO=1

#Known Upstream Gaps

• AddressModeClampToZero
• AddressModeClampToBorder

#Troubleshooting

• Check diagnostics: @wgpu.native_diagnostic()
• Verify that you extracted the official upstream archive, not just the bare library file
• Verify file path and filename for your platform
• If using dynamic mode, set MBT_WGPU_LINK_MODE=dynamic
• If using a custom dynamic library location, set MBT_WGPU_NATIVE_LIB=/absolute/path/to/libwgpu_native.(dylib|so|dll)