{"_id":"@bun-win32/windowscodecs","_rev":"3-d69541bd4ab38fcfb3c8e30700102981","name":"@bun-win32/windowscodecs","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@bun-win32/windowscodecs","version":"1.0.0","keywords":["bun","ffi","win32","windows","windowscodecs","wic","image","codec","bindings","typescript","dll"],"author":"Stev Peifer <stev@bell.net>","license":"MIT","_id":"@bun-win32/windowscodecs@1.0.0","maintainers":[{"name":"obscuritysrl","email":"stev@bell.net"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"7ede0c1f85cf4a9bfaac8a6d4d28ff7cd962bf58","tarball":"https://registry.npmjs.org/@bun-win32/windowscodecs/-/windowscodecs-1.0.0.tgz","fileCount":6,"integrity":"sha512-KZImoLCYT2BfVvVIhRA6GAqZs3AvNFHFzuFipDNdt8m9eMqosIemM5vf+sqmWe8BuI314fsbyOWtEnJdRk2sMA==","signatures":[{"sig":"MEUCICe4QZYJfk0e0yN7zELxevFsdJYnkBGZXxVKoqxCEWUEAiEArNA9Nt+N5VgDYc/slgWRUYHGAHXt8EpJ+qCs7x40DQ4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72122},"main":"./index.ts","type":"module","module":"index.ts","shasum":"7ede0c1f85cf4a9bfaac8a6d4d28ff7cd962bf58","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:plasma-forge":"bun ./example/plasma-forge.ts","example:image-inspector":"bun ./example/image-inspector.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev@bell.net"},"_integrity":"sha512-KZImoLCYT2BfVvVIhRA6GAqZs3AvNFHFzuFipDNdt8m9eMqosIemM5vf+sqmWe8BuI314fsbyOWtEnJdRk2sMA==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/windowscodecs"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 WINDOWSCODECS bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","dependencies":{"@bun-win32/core":"1.1.2"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","@bun-win32/ole32":"1.0.0"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/windowscodecs_1.0.0_1779073019145_0.424146259322272","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@bun-win32/windowscodecs","version":"2.0.0","keywords":["bun","ffi","win32","windows","windowscodecs","wic","image","codec","bindings","typescript","dll"],"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","_id":"@bun-win32/windowscodecs@2.0.0","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"c5e3565c1699a6f7c7e0c351683068b7d06469ea","tarball":"https://registry.npmjs.org/@bun-win32/windowscodecs/-/windowscodecs-2.0.0.tgz","fileCount":6,"integrity":"sha512-ttmwFfLRkRZh6FGEP+OwfSZS3xYLRdifFcQIMYGn+usKlbFqlkowD0b2m3BHwFkR0ptMc8qq8B8rtzQegUc/gQ==","signatures":[{"sig":"MEYCIQCpW1B9xvtsCGTFaZrdn9BBxeAnTdHZlu1Zf3nMxZSkFQIhAOhTy6ii65IksFw8QB0a4LZUwW1ff1zSDxX/c00JNiXN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74513},"main":"./index.ts","type":"module","module":"index.ts","shasum":"c5e3565c1699a6f7c7e0c351683068b7d06469ea","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:plasma-forge":"bun ./example/plasma-forge.ts","example:image-inspector":"bun ./example/image-inspector.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"_integrity":"sha512-ttmwFfLRkRZh6FGEP+OwfSZS3xYLRdifFcQIMYGn+usKlbFqlkowD0b2m3BHwFkR0ptMc8qq8B8rtzQegUc/gQ==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/windowscodecs"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 WINDOWSCODECS bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"26.3.0","dependencies":{"@bun-win32/core":"2.0.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","@bun-win32/ole32":"2.0.0"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/windowscodecs_2.0.0_1782435990143_0.2843325503465177","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"author":"Stev Peifer <stev.p@outlook.com>","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dependencies":{"@bun-win32/core":"2.0.1"},"description":"Zero-dependency, zero-overhead Win32 WINDOWSCODECS bindings for Bun (FFI) on Windows.","devDependencies":{"@bun-win32/ole32":"2.0.1","@types/bun":"latest"},"exports":{".":"./index.ts"},"license":"MIT","module":"index.ts","name":"@bun-win32/windowscodecs","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/windowscodecs"},"type":"module","version":"2.0.1","main":"./index.ts","keywords":["bun","ffi","win32","windows","windowscodecs","wic","image","codec","bindings","typescript","dll"],"sideEffects":false,"engines":{"bun":">=1.1.0"},"scripts":{"example:plasma-forge":"bun ./example/plasma-forge.ts","example:image-inspector":"bun ./example/image-inspector.ts"},"_id":"@bun-win32/windowscodecs@2.0.1","_integrity":"sha512-UrqjuQFFV59e+3SU1gVbhTjxPvUThBDF1SvOqvD5kZuHtUjducB6r8EZ2MvAnSDw2uX+473AucWE25kQH6HT6w==","_nodeVersion":"26.3.0","_npmVersion":"10.8.3","shasum":"49d4021c0f633f7bb96c3ed61d1283d807921f3f","dist":{"integrity":"sha512-UrqjuQFFV59e+3SU1gVbhTjxPvUThBDF1SvOqvD5kZuHtUjducB6r8EZ2MvAnSDw2uX+473AucWE25kQH6HT6w==","shasum":"49d4021c0f633f7bb96c3ed61d1283d807921f3f","tarball":"https://registry.npmjs.org/@bun-win32/windowscodecs/-/windowscodecs-2.0.1.tgz","fileCount":6,"unpackedSize":74513,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHxeAlIkFCF6pqNnPQJeSJyKTCmPrKuU5Rtt6VRwoHw+AiEAgbBhECn2DSDB7b1iwqZEy6WFwDrK5vKYoIDa+/ViJ5Q="}]},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"directories":{},"maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/windowscodecs_2.0.1_1782438215814_0.5014499535964325"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T02:56:59.031Z","modified":"2026-06-26T01:43:36.074Z","1.0.0":"2026-05-18T02:56:59.318Z","2.0.0":"2026-06-26T01:06:30.270Z","2.0.1":"2026-06-26T01:43:35.961Z"},"bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","homepage":"https://github.com/ObscuritySRL/bun-win32#readme","keywords":["bun","ffi","win32","windows","windowscodecs","wic","image","codec","bindings","typescript","dll"],"repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/windowscodecs"},"description":"Zero-dependency, zero-overhead Win32 WINDOWSCODECS bindings for Bun (FFI) on Windows.","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"readme":"# @bun-win32/windowscodecs\n\nZero-dependency, zero-overhead Win32 WindowsCodecs bindings for [Bun](https://bun.sh) on Windows.\n\n## Overview\n\n`@bun-win32/windowscodecs` exposes the `windowscodecs.dll` exports using [Bun](https://bun.sh)'s FFI. It provides a single class, `WindowsCodecs`, which lazily binds native symbols on first use. You can optionally preload a subset or all symbols up-front via `Preload()`.\n\nWindows Imaging Component (WIC) ships its C-callable surface as flat `*_Proxy` exports: each `IWICInterface_Method_Proxy` forwards to the matching COM vtable method, taking the interface pointer as the first argument. COM interface pointers are passed by value as `bigint` handles; the `**` out-parameters of the create/get functions are caller-allocated 8-byte buffers from which you read the new pointer.\n\nThe bindings are strongly typed for a smooth DX in TypeScript.\n\n## Features\n\n- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.\n- Direct FFI to `windowscodecs.dll` (Windows Imaging Component: image decode/encode, scaling, flip/rotate, pixel-format conversion, palettes, color contexts, and metadata).\n- In-source docs in `structs/WindowsCodecs.ts` with links to Microsoft Docs.\n- Lazy binding on first call; optional eager preload (`WindowsCodecs.Preload()`).\n- No wrapper overhead; calls map 1:1 to native APIs.\n- Strongly-typed Win32 aliases (see `types/WindowsCodecs.ts`).\n\n## Requirements\n\n- [Bun](https://bun.sh) runtime\n- Windows 10 or later\n\n## Installation\n\n```sh\nbun add @bun-win32/windowscodecs\n```\n\n## Quick Start\n\n```ts\nimport WindowsCodecs, { WICDecodeOptions, WINCODEC_SDK_VERSION } from '@bun-win32/windowscodecs';\n\n// Read a COM interface pointer out of an 8-byte slot.\nconst slot = () => Buffer.alloc(8);\nconst ptrOf = (b: Buffer) => b.readBigUInt64LE(0);\n\n// 1. Create the imaging factory (CoInitialize via @bun-win32/ole32 first).\nconst ppFactory = slot();\nWindowsCodecs.WICCreateImagingFactory_Proxy(WINCODEC_SDK_VERSION, ppFactory.ptr!);\nconst factory = ptrOf(ppFactory);\n\n// 2. Decode an image from a file.\nconst path = Buffer.from('C:\\\\Windows\\\\Web\\\\Wallpaper\\\\Windows\\\\img0.jpg\\0', 'utf16le');\nconst ppDecoder = slot();\nWindowsCodecs.IWICImagingFactory_CreateDecoderFromFilename_Proxy(factory, path.ptr!, null, 0x8000_0000, WICDecodeOptions.WICDecodeMetadataCacheOnDemand, ppDecoder.ptr!);\nconst decoder = ptrOf(ppDecoder);\n\n// 3. Grab frame 0 and read its dimensions.\nconst ppFrame = slot();\nWindowsCodecs.IWICBitmapDecoder_GetFrame_Proxy(decoder, 0, ppFrame.ptr!);\nconst frame = ptrOf(ppFrame);\n\nconst w = Buffer.alloc(4);\nconst h = Buffer.alloc(4);\nWindowsCodecs.IWICBitmapSource_GetSize_Proxy(frame, w.ptr!, h.ptr!);\nconsole.log(`${w.readUInt32LE(0)} x ${h.readUInt32LE(0)}`);\n```\n\n> [!NOTE]\n> 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.\n\n## Examples\n\nRun the included examples:\n\n```sh\nbun run example:plasma-forge      # creative: synthesize a plasma field, WIC-resample it, paint truecolor ANSI\nbun run example:image-inspector   # professional: full decode + format conversion + codec/metadata diagnostic\n```\n\n## Notes\n\n- WIC is COM-based. Initialize COM on the calling thread first (e.g. `Ole32.CoInitialize(null)` from `@bun-win32/ole32`) before creating the factory.\n- Interface pointers are reference-counted. Release them with `IUnknown::Release` (via `@bun-win32/ole32`) when done; this package binds the documented WIC surface 1:1 and does not manage lifetimes.\n- Either rely on lazy binding or call `WindowsCodecs.Preload()`.\n- Windows only. Bun runtime required.\n- **SAL types & naming:** nullability is in the **type** — `Optional<T>` (formally optional, SAL `_*opt_`) and `Nullable<T>` (plain `[in]`/`[out]` the docs say can be NULL), the null sentinel derived from `T` (`null` for pointers `LP*`/`P*`, `0n` for handles/by-value addresses); direction is in the **parameter name** — `_out` (`_Out_`), `_in_out` (`_Inout_`), `_In_` bare. See `AI.md` and the repo `AGENTS.md`.\n","readmeFilename":"README.md"}