@bun-win32/d2d1 1.0.0

package/AI.md

@@ -0,0 +1,71 @@
+# AI Guide for @bun-win32/d2d1
+
+How to use this package, not what the Win32 API does.
+
+## Usage
+
+```ts
+import D2D1, { SomeFlag } from '@bun-win32/d2d1';
+
+// Methods bind lazily on first call
+const result = D2D1.SomeFunctionW(arg1, arg2);
+
+// Preload: array, single string, or no args (all symbols)
+D2D1.Preload(['SomeFunctionW', 'AnotherFunction']);
+D2D1.Preload('SomeFunctionW');
+D2D1.Preload();
+```
+
+## Where To Look
+
+| Need                              | Read                 |
+| --------------------------------- | -------------------- |
+| Find a method or its MS Docs link | `structs/D2D1.ts` |
+| Find types, enums, constants      | `types/D2D1.ts`   |
+| Quick examples                    | `README.md`          |
+
+`index.ts` re-exports the class and all types — import from `@bun-win32/d2d1` directly.
+
+## Calling Convention
+
+All documented `d2d1.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
+D2D1.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);
+D2D1.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,75 @@
+# @bun-win32/d2d1
+
+Zero-dependency, zero-overhead Win32 D2D1 bindings for [Bun](https://bun.sh) on Windows.
+
+## Overview
+
+`@bun-win32/d2d1` exposes the `d2d1.dll` exports using [Bun](https://bun.sh)'s FFI. It provides a single class, `D2D1`, which lazily binds native symbols on first use. You can optionally preload a subset or all symbols up-front via `Preload()`.
+
+`d2d1.dll` exports only thirteen flat C functions: the factory/device entry points (`D2D1CreateFactory`, `D2D1CreateDevice`, `D2D1CreateDeviceContext`) and Direct2D's native transform/color math (`D2D1MakeRotateMatrix`, `D2D1MakeSkewMatrix`, `D2D1InvertMatrix`, `D2D1IsMatrixInvertible`, `D2D1ComputeMaximumScaleFactor`, `D2D1ConvertColorSpace`, `D2D1SinCos`, `D2D1Tan`, `D2D1Vec3Length`, `D2D1GetGradientMeshInteriorPointsFromCoonsPatch`). The rest of Direct2D — render targets, brushes, geometry, drawing — is reached through the COM vtable of the `ID2D1Factory` returned by `D2D1CreateFactory`.
+
+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 `d2d1.dll` (Direct2D — GPU-accelerated 2D: factory/device creation plus the native matrix, color-space, and gradient-mesh math).
+- In-source docs in `structs/D2D1.ts` with links to Microsoft Docs.
+- Lazy binding on first call; optional eager preload (`D2D1.Preload()`).
+- No wrapper overhead; calls map 1:1 to native APIs.
+- Strongly-typed Win32 aliases (see `types/D2D1.ts`).
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Windows 10 or later
+
+## Installation
+
+```sh
+bun add @bun-win32/d2d1
+```
+
+## Quick Start
+
+```ts
+import D2D1, { D2D1_FACTORY_TYPE } from '@bun-win32/d2d1';
+
+// IID_ID2D1Factory = 06152247-6f50-465a-9245-118bfd3b6007
+const iid = Buffer.from([
+  0x47, 0x22, 0x15, 0x06, 0x50, 0x6f, 0x5a, 0x46,
+  0x92, 0x45, 0x11, 0x8b, 0xfd, 0x3b, 0x60, 0x07,
+]);
+const ppFactory = Buffer.alloc(8);
+
+const hr = D2D1.D2D1CreateFactory(D2D1_FACTORY_TYPE.D2D1_FACTORY_TYPE_SINGLE_THREADED, iid.ptr, null, ppFactory.ptr);
+if (hr !== 0) throw new Error(`D2D1CreateFactory failed: 0x${(hr >>> 0).toString(16)}`);
+
+const factory = ppFactory.readBigUInt64LE(0);
+console.log(`ID2D1Factory @ 0x${factory.toString(16)}`);
+// ... walk ID2D1Factory::CreateWicBitmapRenderTarget / GetDesktopDpi / Release via the COM vtable.
+
+// Direct2D's native transform engine — no COM required:
+const matrix = Buffer.alloc(24); // D2D1_MATRIX_3X2_F = 6 floats
+D2D1.D2D1MakeRotateMatrix(45, 0n, matrix.ptr); // rotate 45° about the origin
+```
+
+> [!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
+# Real-time animated 3D wireframe driven entirely by Direct2D's native matrix/color math
+bun run example:d2d1-matrix-engine
+
+# Factory creation + DPI probe + exhaustive transform / color-space / Coons-patch report
+bun run example:d2d1-factory-probe
+```
+
+## Notes
+
+- Either rely on lazy binding or call `D2D1.Preload()`.
+- Windows only. Bun runtime required.

package/index.ts

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "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 D2D1 bindings for Bun (FFI) on Windows.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/d2d1",
+  "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/d2d1"
+  },
+  "type": "module",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "d2d1",
+    "direct2d",
+    "bindings",
+    "typescript",
+    "dll"
+  ],
+  "files": [
+    "AI.md",
+    "README.md",
+    "index.ts",
+    "structs/*.ts",
+    "types/*.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "example:d2d1-matrix-engine": "bun ./example/d2d1-matrix-engine.ts",
+    "example:d2d1-factory-probe": "bun ./example/d2d1-factory-probe.ts"
+  }
+}

package/structs/D2D1.ts

@@ -0,0 +1,178 @@
+import { type FFIFunction, FFIType } from 'bun:ffi';
+
+import { Win32 } from '@bun-win32/core';
+
+import type {
+  BOOL,
+  FLOAT,
+  HRESULT,
+  IDXGIDevice,
+  IDXGISurface,
+  LPLPVOID,
+  NULL,
+  PACKED_D2D1_POINT_2F,
+  PD2D1_COLOR_F,
+  PD2D1_CREATION_PROPERTIES,
+  PD2D1_FACTORY_OPTIONS,
+  PD2D1_MATRIX_3X2_F,
+  PD2D1_POINT_2F,
+  PFLOAT,
+  PID2D1Device,
+  PID2D1DeviceContext,
+  REFIID,
+} from '../types/D2D1';
+import type { D2D1_COLOR_SPACE, D2D1_FACTORY_TYPE } from '../types/D2D1';
+
+/**
+ * Thin, lazy-loaded FFI bindings for `d2d1.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.
+ *
+ * `d2d1.dll` exposes only thirteen flat C exports; the rest of Direct2D is reached
+ * through the COM vtable of the `ID2D1Factory` obtained from `D2D1CreateFactory`.
+ *
+ * @example
+ * ```ts
+ * import D2D1, { D2D1_FACTORY_TYPE } from './structs/D2D1';
+ *
+ * // Lazy: bind on first call
+ * const iid = Buffer.alloc(16);
+ * const ppFactory = Buffer.alloc(8);
+ * const hr = D2D1.D2D1CreateFactory(D2D1_FACTORY_TYPE.D2D1_FACTORY_TYPE_SINGLE_THREADED, iid.ptr, null, ppFactory.ptr);
+ *
+ * // Or preload a subset to avoid per-symbol lazy binding cost
+ * D2D1.Preload(['D2D1CreateFactory', 'D2D1MakeRotateMatrix']);
+ * ```
+ */
+class D2D1 extends Win32 {
+  protected static override name = 'd2d1.dll';
+
+  /** @inheritdoc */
+  protected static override readonly Symbols = {
+    D2D1ComputeMaximumScaleFactor: { args: [FFIType.ptr], returns: FFIType.f32 },
+    D2D1ConvertColorSpace: { args: [FFIType.ptr, FFIType.u32, FFIType.u32, FFIType.ptr], returns: FFIType.ptr },
+    D2D1CreateDevice: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D2D1CreateDeviceContext: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D2D1CreateFactory: { args: [FFIType.u32, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    D2D1GetGradientMeshInteriorPointsFromCoonsPatch: {
+      args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+      returns: FFIType.void,
+    },
+    D2D1InvertMatrix: { args: [FFIType.ptr], returns: FFIType.i32 },
+    D2D1IsMatrixInvertible: { args: [FFIType.ptr], returns: FFIType.i32 },
+    D2D1MakeRotateMatrix: { args: [FFIType.f32, FFIType.u64, FFIType.ptr], returns: FFIType.void },
+    D2D1MakeSkewMatrix: { args: [FFIType.f32, FFIType.f32, FFIType.u64, FFIType.ptr], returns: FFIType.void },
+    D2D1SinCos: { args: [FFIType.f32, FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+    D2D1Tan: { args: [FFIType.f32], returns: FFIType.f32 },
+    D2D1Vec3Length: { args: [FFIType.f32, FFIType.f32, FFIType.f32], returns: FFIType.f32 },
+  } as const satisfies Record<string, FFIFunction>;
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_2/nf-d2d1_2-d2d1computemaximumscalefactor
+  public static D2D1ComputeMaximumScaleFactor(matrix: PD2D1_MATRIX_3X2_F): FLOAT {
+    return D2D1.Load('D2D1ComputeMaximumScaleFactor')(matrix);
+  }
+
+  // The x64 ABI returns the 16-byte D2D1_COLOR_F by hidden pointer: the caller allocates the
+  // result buffer and passes it as an implicit leading argument; the same pointer is returned.
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_1/nf-d2d1_1-d2d1convertcolorspace
+  public static D2D1ConvertColorSpace(convertedColor: PD2D1_COLOR_F, sourceColorSpace: D2D1_COLOR_SPACE, destinationColorSpace: D2D1_COLOR_SPACE, color: PD2D1_COLOR_F): PD2D1_COLOR_F {
+    return D2D1.Load('D2D1ConvertColorSpace')(convertedColor, sourceColorSpace, destinationColorSpace, color);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_1/nf-d2d1_1-d2d1createdevice
+  public static D2D1CreateDevice(dxgiDevice: IDXGIDevice, creationProperties: PD2D1_CREATION_PROPERTIES | NULL, d2dDevice: PID2D1Device): HRESULT {
+    return D2D1.Load('D2D1CreateDevice')(dxgiDevice, creationProperties, d2dDevice);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_1/nf-d2d1_1-d2d1createdevicecontext
+  public static D2D1CreateDeviceContext(dxgiSurface: IDXGISurface, creationProperties: PD2D1_CREATION_PROPERTIES | NULL, d2dDeviceContext: PID2D1DeviceContext): HRESULT {
+    return D2D1.Load('D2D1CreateDeviceContext')(dxgiSurface, creationProperties, d2dDeviceContext);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1/nf-d2d1-d2d1createfactory
+  public static D2D1CreateFactory(factoryType: D2D1_FACTORY_TYPE, riid: REFIID, pFactoryOptions: PD2D1_FACTORY_OPTIONS | NULL, ppIFactory: LPLPVOID): HRESULT {
+    return D2D1.Load('D2D1CreateFactory')(factoryType, riid, pFactoryOptions, ppIFactory);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_3/nf-d2d1_3-d2d1getgradientmeshinteriorpointsfromcoonspatch
+  public static D2D1GetGradientMeshInteriorPointsFromCoonsPatch(
+    pPoint0: PD2D1_POINT_2F,
+    pPoint1: PD2D1_POINT_2F,
+    pPoint2: PD2D1_POINT_2F,
+    pPoint3: PD2D1_POINT_2F,
+    pPoint4: PD2D1_POINT_2F,
+    pPoint5: PD2D1_POINT_2F,
+    pPoint6: PD2D1_POINT_2F,
+    pPoint7: PD2D1_POINT_2F,
+    pPoint8: PD2D1_POINT_2F,
+    pPoint9: PD2D1_POINT_2F,
+    pPoint10: PD2D1_POINT_2F,
+    pPoint11: PD2D1_POINT_2F,
+    pTensorPoint11: PD2D1_POINT_2F,
+    pTensorPoint12: PD2D1_POINT_2F,
+    pTensorPoint21: PD2D1_POINT_2F,
+    pTensorPoint22: PD2D1_POINT_2F,
+  ): void {
+    return D2D1.Load('D2D1GetGradientMeshInteriorPointsFromCoonsPatch')(
+      pPoint0,
+      pPoint1,
+      pPoint2,
+      pPoint3,
+      pPoint4,
+      pPoint5,
+      pPoint6,
+      pPoint7,
+      pPoint8,
+      pPoint9,
+      pPoint10,
+      pPoint11,
+      pTensorPoint11,
+      pTensorPoint12,
+      pTensorPoint21,
+      pTensorPoint22,
+    );
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1/nf-d2d1-d2d1invertmatrix
+  public static D2D1InvertMatrix(matrix: PD2D1_MATRIX_3X2_F): BOOL {
+    return D2D1.Load('D2D1InvertMatrix')(matrix);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1/nf-d2d1-d2d1ismatrixinvertible
+  public static D2D1IsMatrixInvertible(matrix: PD2D1_MATRIX_3X2_F): BOOL {
+    return D2D1.Load('D2D1IsMatrixInvertible')(matrix);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1/nf-d2d1-d2d1makerotatematrix
+  public static D2D1MakeRotateMatrix(angle: FLOAT, center: PACKED_D2D1_POINT_2F, matrix: PD2D1_MATRIX_3X2_F): void {
+    return D2D1.Load('D2D1MakeRotateMatrix')(angle, center, matrix);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1/nf-d2d1-d2d1makeskewmatrix
+  public static D2D1MakeSkewMatrix(angleX: FLOAT, angleY: FLOAT, center: PACKED_D2D1_POINT_2F, matrix: PD2D1_MATRIX_3X2_F): void {
+    return D2D1.Load('D2D1MakeSkewMatrix')(angleX, angleY, center, matrix);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_1/nf-d2d1_1-d2d1sincos
+  public static D2D1SinCos(angle: FLOAT, s: PFLOAT, c: PFLOAT): void {
+    return D2D1.Load('D2D1SinCos')(angle, s, c);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_1/nf-d2d1_1-d2d1tan
+  public static D2D1Tan(angle: FLOAT): FLOAT {
+    return D2D1.Load('D2D1Tan')(angle);
+  }
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/d2d1_1/nf-d2d1_1-d2d1vec3length
+  public static D2D1Vec3Length(x: FLOAT, y: FLOAT, z: FLOAT): FLOAT {
+    return D2D1.Load('D2D1Vec3Length')(x, y, z);
+  }
+}
+
+export default D2D1;

package/types/D2D1.ts

@@ -0,0 +1,59 @@
+import type { Pointer } from 'bun:ffi';
+
+export type { BOOL, HRESULT, NULL } from '@bun-win32/core';
+
+export enum D2D1_COLOR_SPACE {
+  D2D1_COLOR_SPACE_CUSTOM = 0,
+  D2D1_COLOR_SPACE_FORCE_DWORD = 0xffff_ffff,
+  D2D1_COLOR_SPACE_SCRGB = 2,
+  D2D1_COLOR_SPACE_SRGB = 1,
+}
+
+export enum D2D1_DEBUG_LEVEL {
+  D2D1_DEBUG_LEVEL_ERROR = 1,
+  D2D1_DEBUG_LEVEL_FORCE_DWORD = 0xffff_ffff,
+  D2D1_DEBUG_LEVEL_INFORMATION = 3,
+  D2D1_DEBUG_LEVEL_NONE = 0,
+  D2D1_DEBUG_LEVEL_WARNING = 2,
+}
+
+export enum D2D1_DEVICE_CONTEXT_OPTIONS {
+  D2D1_DEVICE_CONTEXT_OPTIONS_ENABLE_MULTITHREADED_OPTIMIZATIONS = 1,
+  D2D1_DEVICE_CONTEXT_OPTIONS_FORCE_DWORD = 0xffff_ffff,
+  D2D1_DEVICE_CONTEXT_OPTIONS_NONE = 0,
+}
+
+export enum D2D1_FACTORY_TYPE {
+  D2D1_FACTORY_TYPE_FORCE_DWORD = 0xffff_ffff,
+  D2D1_FACTORY_TYPE_MULTI_THREADED = 1,
+  D2D1_FACTORY_TYPE_SINGLE_THREADED = 0,
+}
+
+export enum D2D1_THREADING_MODE {
+  D2D1_THREADING_MODE_MULTI_THREADED = 1,
+  D2D1_THREADING_MODE_SINGLE_THREADED = 0,
+}
+
+export type FLOAT = number;
+export type IDXGIDevice = Pointer;
+export type IDXGISurface = Pointer;
+export type LPLPVOID = Pointer;
+export type PACKED_D2D1_POINT_2F = bigint;
+export type PD2D1_COLOR_F = Pointer;
+export type PD2D1_CREATION_PROPERTIES = Pointer;
+export type PD2D1_FACTORY_OPTIONS = Pointer;
+export type PD2D1_MATRIX_3X2_F = Pointer;
+export type PD2D1_POINT_2F = Pointer;
+export type PFLOAT = Pointer;
+export type PID2D1Device = Pointer;
+export type PID2D1DeviceContext = Pointer;
+export type REFIID = Pointer;
+
+const _packPointBuffer = Buffer.alloc(8);
+
+/** Pack two `FLOAT` values into a `PACKED_D2D1_POINT_2F` for Win32 functions that take `D2D1_POINT_2F` by value (8 bytes, passed in a single x64 register). */
+export function packD2D1_POINT_2F(x: number, y: number): PACKED_D2D1_POINT_2F {
+  _packPointBuffer.writeFloatLE(x, 0);
+  _packPointBuffer.writeFloatLE(y, 4);
+  return _packPointBuffer.readBigUInt64LE(0);
+}