@bun-win32/d3d12 1.0.0

package/AI.md

@@ -0,0 +1,71 @@
+# AI Guide for @bun-win32/d3d12
+
+How to use this package, not what the Win32 API does.
+
+## Usage
+
+```ts
+import D3d12, { SomeFlag } from '@bun-win32/d3d12';
+
+// Methods bind lazily on first call
+const result = D3d12.SomeFunctionW(arg1, arg2);
+
+// Preload: array, single string, or no args (all symbols)
+D3d12.Preload(['SomeFunctionW', 'AnotherFunction']);
+D3d12.Preload('SomeFunctionW');
+D3d12.Preload();
+```
+
+## Where To Look
+
+| Need                              | Read                 |
+| --------------------------------- | -------------------- |
+| Find a method or its MS Docs link | `structs/D3d12.ts` |
+| Find types, enums, constants      | `types/D3d12.ts`   |
+| Quick examples                    | `README.md`          |
+
+`index.ts` re-exports the class and all types — import from `@bun-win32/d3d12` directly.
+
+## Calling Convention
+
+All documented `d3d12.dll` exports are bound. Each method maps 1:1 to its DLL export. Names, parameter names, and order match Microsoft Docs.
+
+### Strings
+
+`W` methods take UTF-16LE NUL-terminated buffers. `A` methods take ANSI strings.
+
+```ts
+const wide = Buffer.from('Hello\0', 'utf16le');  // LPCWSTR
+D3d12.SomeFunctionW(wide.ptr);
+
+// Reading a wide string back from a buffer:
+const text = new TextDecoder('utf-16').decode(buf).replace(/\0.*$/, '');
+```
+
+### Return types
+
+- `HANDLE`, `HWND`, etc. → `bigint`
+- `DWORD`, `UINT`, `BOOL`, `INT`, `LONG` → `number`
+- `LPVOID`, `LPWSTR`, etc. → `Pointer`
+- Win32 `BOOL` is `number` (0 or non-zero), **not** JS `boolean`. Do not compare with `=== true`.
+
+### Pointers, handles, out-parameters
+
+- **Pointer** params (`LP*`, `P*`, `Pointer`): pass `buffer.ptr` from a caller-allocated `Buffer`.
+- **Handle** params (`HANDLE`, `HWND`, etc.): pass a `bigint` value.
+- **Out-parameters**: allocate a `Buffer`, pass `.ptr`, read the result after the call.
+
+```ts
+const out = Buffer.alloc(4);
+D3d12.SomeFunction(out.ptr);
+const value = out.readUInt32LE(0);
+```
+
+### Nullability
+
+- `| NULL` in a signature → pass `null` (optional pointer).
+- `| 0n` in a signature → pass `0n` (optional handle).
+
+## Errors and Cleanup
+
+Return values are raw. If the Win32 function uses last-error semantics, read via `GetLastError()`. Resource cleanup is your responsibility — same as raw Win32.

package/README.md

@@ -0,0 +1,80 @@
+# @bun-win32/d3d12
+
+Zero-dependency, zero-overhead Win32 D3D12 bindings for [Bun](https://bun.sh) on Windows.
+
+## Overview
+
+`@bun-win32/d3d12` exposes the `d3d12.dll` exports using [Bun](https://bun.sh)'s FFI. It provides a single class, `D3d12`, which lazily binds native symbols on first use. You can optionally preload a subset or all symbols up-front via `Preload()`.
+
+The bindings are strongly typed for a smooth DX in TypeScript.
+
+## Features
+
+- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.
+- Direct FFI to `d3d12.dll` (Direct3D 12 device creation, debug-layer access, global interface retrieval, and root-signature serialize/deserialize).
+- In-source docs in `structs/D3d12.ts` with links to Microsoft Docs.
+- Lazy binding on first call; optional eager preload (`D3d12.Preload()`).
+- No wrapper overhead; calls map 1:1 to native APIs.
+- Strongly-typed Win32 aliases (see `types/D3d12.ts`).
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Windows 10 or later
+
+## Installation
+
+```sh
+bun add @bun-win32/d3d12
+```
+
+## Quick Start
+
+```ts
+import D3d12, { D3D_FEATURE_LEVEL } from '@bun-win32/d3d12';
+
+// IID_ID3D12Device {189819f1-1db6-4b57-be54-1821339b85f7}
+const iidDevice = Buffer.alloc(16);
+iidDevice.writeUInt32LE(0x189819f1, 0);
+iidDevice.writeUInt16LE(0x1db6, 4);
+iidDevice.writeUInt16LE(0x4b57, 6);
+Buffer.from([0xbe, 0x54, 0x18, 0x21, 0x33, 0x9b, 0x85, 0xf7]).copy(iidDevice, 8);
+
+// Pass NULL for ppDevice to test support without creating the device:
+// S_OK / S_FALSE means a D3D12-capable adapter exists at this feature level.
+const hr = D3d12.D3D12CreateDevice(null, D3D_FEATURE_LEVEL.D3D_FEATURE_LEVEL_11_0, iidDevice.ptr, null);
+if (hr === 0 || hr === 1) {
+  console.log('D3D12 supported at feature level 11_0');
+}
+
+// Allocate an 8-byte slot and pass its .ptr to actually receive the device,
+// then drive ID3D12Device via its COM vtable and call Release when done.
+const ppDevice = Buffer.alloc(8);
+const created = D3d12.D3D12CreateDevice(null, D3D_FEATURE_LEVEL.D3D_FEATURE_LEVEL_11_0, iidDevice.ptr, ppDevice.ptr);
+if (created === 0) {
+  const deviceAddress = ppDevice.readBigUInt64LE(0);
+  console.log(`ID3D12Device @ 0x${deviceAddress.toString(16)}`);
+}
+```
+
+> [!NOTE]
+> AI agents: see `AI.md` for the package binding contract and source-navigation guidance. It explains how to use the package without scanning the entire implementation.
+
+## Examples
+
+Run the included examples:
+
+```sh
+# Thorough flat-FFI diagnostic: feature-level ladder, debug/SDK interfaces,
+# and root-signature serialize -> deserialize round-trips
+bun run example:d3d12-device-probe
+
+# Creative: create a real ID3D12Device and x-ray its hidden capability
+# matrix (ray tracing, mesh shaders, wave ops, ...) via CheckFeatureSupport
+bun run example:d3d12-capability-xray
+```
+
+## Notes
+
+- Either rely on lazy binding or call `D3d12.Preload()`.
+- Windows only. Bun runtime required.

package/index.ts

@@ -0,0 +1,4 @@
+import D3d12 from './structs/D3d12';
+
+export * from './types/D3d12';
+export default D3d12;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "author": "Stev Peifer <stev@bell.net>",
+  "bugs": {
+    "url": "https://github.com/ObscuritySRL/bun-win32/issues"
+  },
+  "dependencies": {
+    "@bun-win32/core": "1.1.2"
+  },
+  "description": "Zero-dependency, zero-overhead Win32 D3D12 bindings for Bun (FFI) on Windows.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/d3d12",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "private": false,
+  "homepage": "https://github.com/ObscuritySRL/bun-win32#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ObscuritySRL/bun-win32.git",
+    "directory": "packages/d3d12"
+  },
+  "type": "module",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "d3d12",
+    "bindings",
+    "typescript",
+    "dll"
+  ],
+  "files": [
+    "AI.md",
+    "README.md",
+    "index.ts",
+    "structs/*.ts",
+    "types/*.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "example:d3d12-device-probe": "bun ./example/d3d12-device-probe.ts",
+    "example:d3d12-capability-xray": "bun ./example/d3d12-capability-xray.ts"
+  }
+}

package/structs/D3d12.ts

@@ -0,0 +1,88 @@
+import { type FFIFunction, FFIType } from 'bun:ffi';
+
+import { Win32 } from '@bun-win32/core';
+
+import type { HRESULT, IUnknown, LPCVOID, LPLPVOID, LPVOID, NULL, PD3D12_ROOT_SIGNATURE_DESC, PD3D12_VERSIONED_ROOT_SIGNATURE_DESC, PID3DBlob, PUINT, REFCLSID, REFIID, SIZE_T, UINT } from '../types/D3d12';
+import type { D3D_FEATURE_LEVEL, D3D_ROOT_SIGNATURE_VERSION } from '../types/D3d12';
+
+/**
+ * Thin, lazy-loaded FFI bindings for `d3d12.dll`.
+ *
+ * Each static method corresponds one-to-one with a Win32 export declared in `Symbols`.
+ * The first call to a method binds the underlying native symbol via `bun:ffi` and
+ * memoizes it on the class for subsequent calls. For bulk, up-front binding, use `Preload`.
+ *
+ * Symbols are defined with explicit `FFIType` signatures and kept alphabetized.
+ * You normally do not access `Symbols` directly; call the static methods or preload
+ * a subset for hot paths.
+ *
+ * @example
+ * ```ts
+ * import D3d12, { D3D_FEATURE_LEVEL } from './structs/D3d12';
+ *
+ * // Lazy: bind on first call
+ * const iidDevice = Buffer.alloc(16);
+ * const ppDevice = Buffer.alloc(8);
+ * const hr = D3d12.D3D12CreateDevice(null, D3D_FEATURE_LEVEL.D3D_FEATURE_LEVEL_11_0, iidDevice.ptr, ppDevice.ptr);
+ *
+ * // Or preload a subset to avoid per-symbol lazy binding cost
+ * D3d12.Preload(['D3D12CreateDevice', 'D3D12GetDebugInterface']);
+ * ```
+ */
+class D3d12 extends Win32 {
+  protected static override name = 'd3d12.dll';
+
+  /** @inheritdoc */
+  protected static override readonly Symbols = {
+    D3D12CreateDevice: { args: [FFIType.ptr, FFIType.u32, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12CreateRootSignatureDeserializer: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12CreateVersionedRootSignatureDeserializer: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12EnableExperimentalFeatures: { args: [FFIType.u32, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12GetDebugInterface: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12GetInterface: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12SerializeRootSignature: { args: [FFIType.ptr, FFIType.u32, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D3D12SerializeVersionedRootSignature: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+  } as const satisfies Record<string, FFIFunction>;
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12createdevice
+  public static D3D12CreateDevice(pAdapter: IUnknown | NULL, MinimumFeatureLevel: D3D_FEATURE_LEVEL, riid: REFIID, ppDevice: LPLPVOID | NULL): HRESULT {
+    return D3d12.Load('D3D12CreateDevice')(pAdapter, MinimumFeatureLevel, riid, ppDevice);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12createrootsignaturedeserializer
+  public static D3D12CreateRootSignatureDeserializer(pSrcData: LPCVOID, SrcDataSizeInBytes: SIZE_T, pRootSignatureDeserializerInterface: REFIID, ppRootSignatureDeserializer: LPLPVOID): HRESULT {
+    return D3d12.Load('D3D12CreateRootSignatureDeserializer')(pSrcData, SrcDataSizeInBytes, pRootSignatureDeserializerInterface, ppRootSignatureDeserializer);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12createversionedrootsignaturedeserializer
+  public static D3D12CreateVersionedRootSignatureDeserializer(pSrcData: LPCVOID, SrcDataSizeInBytes: SIZE_T, pRootSignatureDeserializerInterface: REFIID, ppRootSignatureDeserializer: LPLPVOID): HRESULT {
+    return D3d12.Load('D3D12CreateVersionedRootSignatureDeserializer')(pSrcData, SrcDataSizeInBytes, pRootSignatureDeserializerInterface, ppRootSignatureDeserializer);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12enableexperimentalfeatures
+  public static D3D12EnableExperimentalFeatures(NumFeatures: UINT, pIIDs: REFIID, pConfigurationStructs: LPVOID | NULL, pConfigurationStructSizes: PUINT | NULL): HRESULT {
+    return D3d12.Load('D3D12EnableExperimentalFeatures')(NumFeatures, pIIDs, pConfigurationStructs, pConfigurationStructSizes);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12getdebuginterface
+  public static D3D12GetDebugInterface(riid: REFIID, ppvDebug: LPLPVOID | NULL): HRESULT {
+    return D3d12.Load('D3D12GetDebugInterface')(riid, ppvDebug);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12getinterface
+  public static D3D12GetInterface(rclsid: REFCLSID, riid: REFIID, ppvDebug: LPLPVOID | NULL): HRESULT {
+    return D3d12.Load('D3D12GetInterface')(rclsid, riid, ppvDebug);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12serializerootsignature
+  public static D3D12SerializeRootSignature(pRootSignature: PD3D12_ROOT_SIGNATURE_DESC, Version: D3D_ROOT_SIGNATURE_VERSION, ppBlob: PID3DBlob, ppErrorBlob: PID3DBlob | NULL): HRESULT {
+    return D3d12.Load('D3D12SerializeRootSignature')(pRootSignature, Version, ppBlob, ppErrorBlob);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12serializeversionedrootsignature
+  public static D3D12SerializeVersionedRootSignature(pRootSignature: PD3D12_VERSIONED_ROOT_SIGNATURE_DESC, ppBlob: PID3DBlob, ppErrorBlob: PID3DBlob | NULL): HRESULT {
+    return D3d12.Load('D3D12SerializeVersionedRootSignature')(pRootSignature, ppBlob, ppErrorBlob);
+  }
+}
+
+export default D3d12;

package/types/D3d12.ts

@@ -0,0 +1,32 @@
+import type { Pointer } from 'bun:ffi';
+
+export type { HRESULT, LPCVOID, LPVOID, NULL, SIZE_T, UINT } from '@bun-win32/core';
+
+export enum D3D_FEATURE_LEVEL {
+  D3D_FEATURE_LEVEL_10_0 = 0xa000,
+  D3D_FEATURE_LEVEL_10_1 = 0xa100,
+  D3D_FEATURE_LEVEL_11_0 = 0xb000,
+  D3D_FEATURE_LEVEL_11_1 = 0xb100,
+  D3D_FEATURE_LEVEL_12_0 = 0xc000,
+  D3D_FEATURE_LEVEL_12_1 = 0xc100,
+  D3D_FEATURE_LEVEL_12_2 = 0xc200,
+  D3D_FEATURE_LEVEL_1_0_CORE = 0x1000,
+  D3D_FEATURE_LEVEL_9_1 = 0x9100,
+  D3D_FEATURE_LEVEL_9_2 = 0x9200,
+  D3D_FEATURE_LEVEL_9_3 = 0x9300,
+}
+
+export enum D3D_ROOT_SIGNATURE_VERSION {
+  D3D_ROOT_SIGNATURE_VERSION_1 = 0x1,
+  D3D_ROOT_SIGNATURE_VERSION_1_0 = 0x1,
+  D3D_ROOT_SIGNATURE_VERSION_1_1 = 0x2,
+}
+
+export type IUnknown = Pointer;
+export type LPLPVOID = Pointer;
+export type PD3D12_ROOT_SIGNATURE_DESC = Pointer;
+export type PD3D12_VERSIONED_ROOT_SIGNATURE_DESC = Pointer;
+export type PID3DBlob = Pointer;
+export type PUINT = Pointer;
+export type REFCLSID = Pointer;
+export type REFIID = Pointer;