(image-bitmap …)

Creates an image bitmap from an encoded image file that a (data … :file …) entry embeds in the PNGB payload (the compiled bytecode), for loading textures.

Syntax

(image-bitmap :name name :data dataName)

Keys

Key	Type	Required	Default	Description
`:name`	symbol	Yes	-	Unique image-bitmap name
`:data`	reference	Yes	-	Reference to a `(data … :file …)` entry

:data

Type: reference

Reference to a (data …) form holding an encoded image file (a :file path plus its :mime type).

(data :name pngFile :file "textures/diffuse.png" :mime "image/png")

(image-bitmap :name diffuseImage :data pngFile)

The decoded image is uploaded into a texture via a (copy-external-image-to-texture …) queue action. The destination texture needs copy-dst in its :usage, and can take its dimensions from the image by naming it in :size.

Examples

Load PNG Texture

(data :name textureFile :file "assets/logo.png" :mime "image/png")

(image-bitmap :name logo :data textureFile)

(texture :name logoTexture
  :size logo
  :format rgba8unorm
  :usage [texture-binding copy-dst render-attachment])

(queue :name loadLogo
  (copy-external-image-to-texture (source :image logo) (destination :texture logoTexture)))

(sampler :name linearSampler
  :mag-filter linear
  :min-filter linear)

(bind-group :name textureGroup :layout pipeline :group 0
  (entry :binding 0 :texture logoTexture)
  (entry :binding 1 :sampler linearSampler))

Multiple Textures

(data :name diffuseFile :file "textures/diffuse.png" :mime "image/png")
(data :name normalFile :file "textures/normal.png" :mime "image/png")

(image-bitmap :name diffuseImg :data diffuseFile)
(image-bitmap :name normalImg :data normalFile)

; One (queue …) can carry several actions, run in document order. A frame's
; :init list takes compute passes only, so an upload queue goes in :perform.
(queue :name loadTextures
  (copy-external-image-to-texture (source :image diffuseImg) (destination :texture diffuseMap))
  (copy-external-image-to-texture (source :image normalImg) (destination :texture normalMap)))

(frame :name main
  :perform [loadTextures render])

Sprite Sheet

(data :name spriteSheet :file "sprites/sheet.png" :mime "image/png")

(image-bitmap :name sprites :data spriteSheet)

(texture :name spriteTexture
  :size sprites
  :format rgba8unorm
  :usage [texture-binding copy-dst])

(queue :name loadSprites
  (copy-external-image-to-texture (source :image sprites) (destination :texture spriteTexture)))

Supported Formats

The browser’s createImageBitmap API is used, so all browser-supported formats work:

PNG
JPEG
GIF
WebP
SVG (rasterized)

Validation Rules

Rule	Error
A name is declared once, across every form kind	`duplicate_cross_ref_target`, or `duplicate name 'x': already declared as an (image-bitmap …) at line N`
`:data` key is required	`missing_required_key`
Referenced data must exist	`not_cross_ref`
The `:file` must be readable at compile time	`cannot read 'assets/logo.png': FileNotFound` (located on the `(data …)` form; the path is resolved against the document’s directory)

The referenced (data …) must carry a :file; pointing :data at a :float32 or shape entry compiles, but produces no image bytes to decode at runtime.

WebGPU Mapping

At runtime, converts to ImageBitmap for use with copyExternalImageToTexture:

const blob = new Blob([data], { type: mimeType });
const imageBitmap = await createImageBitmap(blob);

(data …) - Define blob data
(texture …) - Target textures
(queue …) - Copy to textures