Working with Images

Images are a powerful way to add visual content to your FxCanvas applications. FxCanvas supports drawing images through the Image class and drawImage() method. Images can be loaded from URLs, created from binary data, or used in patterns and other operations.

Creating Images

From URLs

Load images from web URLs:

import { CanvasEncoder, Image } from 'fxcanvas';

const canvas = new CanvasEncoder(400, 200);

// Create image - loads automatically
const img = new Image('/path/to/image.png');

console.log(img.width, img.height); // Image dimensions available immediately

From Binary Data

Create images from Uint8Array data:

import { ImageMimeType } from 'fxcanvas';

// PNG image from data
const pngData = new Uint8Array(/* PNG bytes */);
const img = new Image(pngData, ImageMimeType.Png);

// JPEG with explicit dimensions
const jpegData = new Uint8Array(/* JPEG bytes */);
const img2 = new Image(jpegData, ImageMimeType.Jpeg, 800, 600);

Raw Pixel Data

Create images from raw RGBA pixel data:

const width = 100;
const height = 100;
const pixelData = new Uint8Array(width * height * 4); // RGBA

// Fill with red pixels
for (let i = 0; i < pixelData.length; i += 4) {
    pixelData[i] = 255;     // R
    pixelData[i + 1] = 0;   // G
    pixelData[i + 2] = 0;   // B
    pixelData[i + 3] = 255; // A
}

const img = new Image(pixelData, ImageMimeType.Raw, width, height);

Drawing Images

Basic Image Drawing

Draw an image at a specific position:

// Draw image at (50, 50)
canvas.drawImage(img, 50, 50);

Scaled Drawing

Draw an image with custom size:

// Draw image scaled to 200x150 at (50, 50)
canvas.drawImage(img, 50, 50, 200, 150);

Cropped and Scaled Drawing

Draw a portion of an image, scaled to fit:

// Draw 100x100 region from source at (10, 10)
// Scale to 200x200 and place at (50, 50)
canvas.drawImage(img, 10, 10, 100, 100, 50, 50, 200, 200);

Image Properties

console.log(img.width);      // Image width in pixels
console.log(img.height);     // Image height in pixels
console.log(img.src);        // Source URL (if loaded from URL)
console.log(img.data);       // Binary data (if loaded from data)
console.log(img.mimeType);   // ImageMimeType enum value

Applying Opacity

You can make images semi-transparent by adjusting the global alpha value before drawing:

// Set 50% opacity
canvas.setGlobalAlpha(0.5);

// Draw the semi-transparent image
canvas.drawImage(img, 50, 50);

// Reset alpha for subsequent drawings
canvas.setGlobalAlpha(1.0);

Opacity works with compositing for advanced blending; see Composite Operations.

Compositing Modes

FxCanvas supports different compositing operations that control how new drawings interact with existing canvas content:

// Set compositing to multiply mode
canvas.setGlobalCompositeOperation('multiply');

// Draw the image with the compositing effect
canvas.drawImage(img, 50, 50);

// Reset to default compositing
canvas.setGlobalCompositeOperation('source-over');

Common modes include 'multiply', 'screen', 'overlay', and 'destination-in' for masking.

Image Transformations

Images respect the current transformation matrix:

// Scale and rotate image
canvas.save();
canvas.translate(100, 100);
canvas.rotate(Math.PI / 4);
canvas.scale(0.5, 0.5);
canvas.drawImage(img, -img.width/2, -img.height/2);
canvas.restore();

Using Images in Patterns

Images can be used to create repeating patterns:

import { Pattern, RepetitionStyle } from 'fxcanvas';

const pattern = new Pattern(img, RepetitionStyle.Repeat);
canvas.setFillStyle(pattern);
canvas.fillRect(0, 0, 200, 200);

For advanced pattern usage, see Working with Patterns.

Working with Raw Image Data

For advanced image manipulation, FxCanvas allows direct access to pixel data.

Reading Pixel Data

// Get the pixel data for a 100x100 area starting at (50, 50)
const imageData = canvas.getImageData(50, 50, 100, 100);

// The data is in imageData.data as a Uint8ClampedArray
// Each pixel has 4 values: red, green, blue, alpha
console.log(imageData.data.length); // 100 * 100 * 4 = 40000

Manipulating Pixel Data

// Invert the colors of the image data
for (let i = 0; i < imageData.data.length; i += 4) {
    imageData.data[i] = 255 - imageData.data[i];     // Red
    imageData.data[i + 1] = 255 - imageData.data[i + 1]; // Green
    imageData.data[i + 2] = 255 - imageData.data[i + 2]; // Blue
    // Alpha (i + 3) remains unchanged
}

Writing Pixel Data Back

// Put the modified image data back at the same position
canvas.putImageData(imageData, 50, 50);

// Update only a 50x50 region
canvas.putImageData(imageData, 50, 50, 25, 25, 50, 50);

Supported Image Formats

FxCanvas supports:

• PNG (ImageMimeType.Png) - Best for graphics with transparency
• JPEG (ImageMimeType.Jpeg) - Best for photographs
• WebP (ImageMimeType.Webp) - Modern format with good compression
• Raw (ImageMimeType.Raw) - Raw RGBA pixel data

Images can incorporate colors; see Working with Colors.

Images can include rendered text; see Fonts and Text.