Pixmaps

Pixmaps provide storage for rectangular regions of pixels.

You can create a new pixmap using the CreatePixmap command, or load a pixmap from a stream using LoadPixmap.

Pixmaps have 5 properties: width, height, a byte pointer to the pixmap's pixels, pitch and format.

You can retrieve a pointer to a pixmap's pixels using the PixmapPixelPtr command.

A pixmap's pitch refers to the number of bytes between one row of pixels in the pixmap and the next. To retrieve a pixmap's pitch, use the PixmapPitch command.

A pixmap's pixel format determines how the pixels within a pixmap are stored in memory. This must be taken into account if you want to access pixels directly via a pixmap's pixel pointer. You can retrieve the format of a pixmap using the PixmapFormat command, and convert pixmap's from one format to another using ConvertPixmap.

You can also resize a pixmap, flip a pixmap horizontally or vertically and more.

Function reference

CreatePixmap:TPixmap( width,height,format,align_bytes=4 )   Create a pixmap

Returns: A new pixmap object of the specified width and height

format should be one of the following:

FormatDescription
PF_RGB88824 bit big endian RGB
PF_BGR88824 bit little endian RGB
PF_RGBA888832 bit big endian RGB with alpha
PF_BGRA888832 bit big endian RGB with alpha


CreateStaticPixmap:TPixmap( pixels:Byte Ptr,width,height,pitch,format )   Create a pixmap with existing data

Returns: A new pixmap object that references an existing block of memory

The memory referenced by a static pixmap is not released when the pixmap is deleted.

See CreatePixmap for valid pixmap formats.


CopyPixmap:TPixmap( pixmap:TPixmap )   Copy a pixmap

Returns: A new pixmap object


ConvertPixmap:TPixmap( pixmap:TPixmap,format )   Convert pixel format of a pixmap

Returns: A new pixmap object with the specified pixel format

See CreatePixmap for valid pixmap formats.


PixmapPitch( pixmap:TPixmap )   Get pixmap pitch

Returns: The pitch, in bytes, of pixmap

Pitch refers to the difference, in bytes, between the start of one row of pixels and the start of the next row.


PixmapFormat( pixmap:TPixmap )   Get pixmap format

Returns: The format of the pixels stored in a pixmap

The returned value will be one of:

FormatDescription
PF_RGB88824 bit big endian RGB
PF_BGR88824 bit little endian RGB
PF_RGBA888832 bit big endian RGB with alpha
PF_BGRA888832 bit big endian RGB with alpha


PixmapPixelPtr:Byte Ptr( pixmap:TPixmap,x=0,y=0 )   Get pixmap pixels

Returns: A byte pointer to the pixels stored in a pixmap


PixmapWindow:TPixmap( pixmap:TPixmap,x,y,width,height )   Create a pixmap window

Returns: A new pixmap object

PixmapWindow returns a 'virtual' window into a pixmap.


MaskPixmap:TPixmap( pixmap:TPixmap,mask_red,mask_green,mask_blue )   Mask a pixmap

Returns: A new pixmap object

MaskPixmap builds a new pixmap with alpha components set to '0' wherever the pixel colors in the original pixmap match mask_red, mask_green and mask_blue. mask_red, mask_green and mask_blue should be in the range 0 to 255.


XFlipPixmap:TPixmap( pixmap:TPixmap )   Flip a pixmap horizontally

Returns: A new pixmap object


YFlipPixmap:TPixmap( pixmap:TPixmap )   Flip a pixmap vertically

Returns: A new pixmap object


ResizePixmap:TPixmap( pixmap:TPixmap,width,height )   Resize a pixmap

Returns: A new pixmap object of the specified width and height


LoadPixmap:TPixmap( url:Object )   Load a pixmap

Returns: A pixmap object


ReadPixel( pixmap:TPixmap,x,y )   Read a pixel from a pixmap

Returns: A 32 bit pixel value

The returned 32 bit value contains the following components:
bits 24-31 : pixel alpha
bits 16-23 : pixel red
bits 8-15 : pixel green
bits 0-7 : pixel blue


WritePixel( pixmap:TPixmap,x,y,argb )   Write a pixel to a pixmap

The 32 bit argb value contains the following components:
bits 24-31 : pixel alpha
bits 16-23 : pixel red
bits 8-15 : pixel green
bits 0-7 : pixel blue


Module Information

Modulebrl.pixmap
Version 1.00
Author Mark Sibly
License Blitz Shared Source Code
Copyright Blitz Research Ltd
Modserver BRL