#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. This repo is pinned to one official upstream release:

• repo: gfx-rs/wgpu-native
• tag: v29.0.1.1
• commit: 6aed50955d934ac36049ba8d002034841633ae02
• release page: https://github.com/gfx-rs/wgpu-native/releases/tag/v29.0.1.1

4. Dynamic mode should use the matching extracted upstream release tree:

• 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

• Dynamic mode resolves lib/libwgpu_native.(dylib|so) on macOS/Linux or lib/wgpu_native.dll on Windows from MBT_WGPU_NATIVE_ROOT
• Static mode reuses lib/libwgpu_native.a (or lib/wgpu_native.lib on Windows) from MBT_WGPU_NATIVE_ROOT instead of downloading again
• Example extracted roots:
  • macOS/Linux: /opt/wgpu-native/wgpu-linux-x86_64-release
  • Windows: C:\\wgpu-native\\wgpu-windows-x86_64-msvc-release

#Quick Example

fn main {
  try {
    @wgpu.with_default_device_queue_managed((instance, device, queue) => {
      let _ = instance
      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()

      let cmd = encoder.finish()
      queue.submit_one(cmd)
    })
  } 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)

let surface = instance.create_surface_from_window(window)

surface.sync_macos_window_handle(window.window_handle())

• Metal: Instance::create_surface_metal_layer()
• macOS AppKit: Instance::create_surface_macos_ns_view(ns_view)
• 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)

• The checked-in host-integration behavior tests are for macOS/Metal.
• The AppKit integration test exercises Milky2018/windowing handle providers, real surface creation, configuration, frame acquisition, presentation, and resize synchronization.
• create_surface_macos_ns_view accepts an AppKit NSView*, installs or reuses a CAMetalLayer, synchronizes its drawable size from the view's backing coordinates, and returns a Surface that retains the layer. Call Surface::sync_macos_ns_view_layer(ns_view) after host-side view resizes.
• Linux and Windows now have checked-in descriptor/input-validation tests for their platform surface entry points.
• Off-target constructors are explicitly gated in the native stubs and return a null Surface instead of attempting a best-effort host integration path.
• Linux/Windows host-backed presentation paths remain experimental until the project has real window-system integration evidence.
• Android remains API-only in this repository until the build/deployment story and on-device validation exist.

• 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 immediates:
  • @wgpu_c.pipeline_layout_descriptor_immediates_many_new(...)
  • Device::create_pipeline_layout_immediates_many(first_stages, first_start, first_end, other_ranges)
  • Device::create_pipeline_layout_with_immediates(bind_group_layouts, ranges)
  • On wgpu-native v29, range-style immediates APIs allocate the maximum requested immediate byte size.
• 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. MBT_WGPU_NATIVE_ROOT
  3. 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_resolved_lib_path() returns the currently resolved dynamic library path, or "" in static mode / when no path can be resolved.
• @wgpu.native_diagnostic() returns a combined loader/support diagnostic string.
• @wgpu.native_recovery_hint() returns the next recommended recovery step for the current loader state.
• For custom dynamic builds without release metadata, set MBT_WGPU_NATIVE_ALLOW_UNVERIFIED=1 to bypass release-metadata verification only. It does not bypass library load failures or missing symbols.
• 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()
  • Device::create_render_pipeline_async_sync_ptr_or_raise(...) is conservatively repo-gated on the supported native release and raises an explicit runtime error; use create_render_pipeline_async_sync_ptr(...) for the safe fallback helper
• 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
  • texture atomics: @wgpu.NATIVE_FEATURE_TEXTURE_ATOMIC
  • 64-bit texture atomics: @wgpu.NATIVE_FEATURE_TEXTURE_INT64_ATOMIC
  • 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

• TEXTURE_FORMAT_R64_UINT
• STORAGE_TEXTURE_ACCESS_ATOMIC

#Troubleshooting

• Check diagnostics: @wgpu.native_diagnostic()
• Check the exact chosen path: @wgpu.native_resolved_lib_path()
• Check the next action directly: @wgpu.native_recovery_hint()
• Verify that you extracted the official upstream archive, not just the bare library file
• Verify file path and filename for your platform
• On Windows x64, use the msvc archive for dynamic installs; the gnu archive is only for the automatic static link path
• If using dynamic mode, set MBT_WGPU_LINK_MODE=dynamic
• If you have a pre-extracted official release tree, set MBT_WGPU_NATIVE_ROOT=/absolute/path/to/extracted/root
• If using a custom dynamic library location, set MBT_WGPU_NATIVE_LIB=/absolute/path/to/libwgpu_native.(dylib|so|dll)
• If you are using a trusted custom build, MBT_WGPU_NATIVE_ALLOW_UNVERIFIED=1 only skips the metadata/tag gate; it does not make an unloadable or symbol-incomplete library work