BRL.Pixmap: Types Functions Source  


Pixmaps provide storage for rectangular regions of pixels.

You can create a new pixmap using the CreatePixmap command, or load a pixmap 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 pixmaps from one format to another using ConvertPixmap.

You can also use ResizePixmap to resize a pixmap and flip a pixmap horizontally or vertically with XFlipPixmap and YFlipPixmap.

Types

TPixmapThe Pixmap type
TPixmapLoaderAbstract base type for pixmap loaders

Functions

CreatePixmapCreate a pixmap
CreateStaticPixmapCreate a pixmap with existing pixel data
CopyPixmapCopy a pixmap
ConvertPixmapConvert pixel format of a pixmap
PixmapWidthGet pixmap width
PixmapHeightGet pixmap width
PixmapPitchGet pixmap pitch
PixmapFormatGet pixmap format
PixmapPixelPtrGet pixmap pixels
PixmapWindowCreate a pixmap window
MaskPixmapMask a pixmap
XFlipPixmapFlip a pixmap horizontally
YFlipPixmapFlip a pixmap vertically
ResizePixmapResize a pixmap
LoadPixmapLoad a pixmap
ReadPixelRead a pixel from a pixmap
WritePixelWrite a pixel to a pixmap
ClearPixelsClear a pixmap

Function reference

Function CreatePixmap:TPixmap( width,height,format,align_bytes=4 )
ReturnsA new pixmap object of the specified width and height
DescriptionCreate a pixmap
Information format should be one of the following:

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

Note that the newly created pixmap will contain random data. ClearPixels can be used to set all pixels to a known value prior to use.

Function CreateStaticPixmap:TPixmap( pixels:Byte Ptr,width,height,pitch,format )
ReturnsA new pixmap object that references an existing block of memory
DescriptionCreate a pixmap with existing pixel data
Information The memory referenced by a static pixmap is not released when the pixmap is deleted.

See CreatePixmap for valid pixmap formats.

Function CopyPixmap:TPixmap( pixmap:TPixmap )
ReturnsA new pixmap object
DescriptionCopy a pixmap

Function ConvertPixmap:TPixmap( pixmap:TPixmap,format )
ReturnsA new pixmap object with the specified pixel format
DescriptionConvert pixel format of a pixmap
Information See CreatePixmap for valid pixmap formats.

Function PixmapWidth( pixmap:TPixmap )
ReturnsThe width, in pixels, of pixmap
DescriptionGet pixmap width

Function PixmapHeight( pixmap:TPixmap )
ReturnsThe height, in pixels, of pixmap
DescriptionGet pixmap width

Function PixmapPitch( pixmap:TPixmap )
ReturnsThe pitch, in bytes, of pixmap
DescriptionGet pixmap pitch
Information Pitch refers to the difference, in bytes, between the start of one row of pixels and the start of the next row.

Function PixmapFormat( pixmap:TPixmap )
ReturnsThe format of the pixels stored in pixmap
DescriptionGet pixmap format
Information See CreatePixmap for supported formats.

Function PixmapPixelPtr:Byte Ptr( pixmap:TPixmap,x=0,y=0 )
ReturnsA byte pointer to the pixels stored in pixmap
DescriptionGet pixmap pixels

Function PixmapWindow:TPixmap( pixmap:TPixmap,x,y,width,height )
ReturnsA new pixmap object
DescriptionCreate a pixmap window
InformationPixmapWindow creates a 'virtual' window into pixmap.

Function MaskPixmap:TPixmap( pixmap:TPixmap,mask_red,mask_green,mask_blue ) NoDebug
ReturnsA new pixmap object
DescriptionMask a pixmap
InformationMaskPixmap 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.

Function XFlipPixmap:TPixmap( pixmap:TPixmap ) NoDebug
ReturnsA new pixmap object
DescriptionFlip a pixmap horizontally

Function YFlipPixmap:TPixmap( pixmap:TPixmap ) NoDebug
ReturnsA new pixmap object
DescriptionFlip a pixmap vertically

Function ResizePixmap:TPixmap( pixmap:TPixmap,width,height ) NoDebug
ReturnsA new pixmap object of the specified width and height
DescriptionResize a pixmap

Function LoadPixmap:TPixmap( url:Object )
ReturnsA pixmap object
DescriptionLoad a pixmap

Function ReadPixel( pixmap:TPixmap,x,y )
ReturnsA 32 bit pixel value
DescriptionRead a pixel from a pixmap
Information The returned 32 bit value contains the following components:

bits 24-31pixel alpha
bits 16-23pixel red
bits 8-15pixel green
bits 0-7pixel blue

Function WritePixel( pixmap:TPixmap,x,y,argb )
DescriptionWrite a pixel to a pixmap
Information The 32 bit argb value contains the following components:

bits 24-31pixel alpha
bits 16-23pixel red
bits 8-15pixel green
bits 0-7pixel blue

Function ClearPixels( pixmap:TPixmap,argb=0 )
DescriptionClear a pixmap
Information Sets all pixels in a pixmap to a 32 bit pixel value.

The 32 bit argb value contains the following components:

bits 24-31pixel alpha
bits 16-23pixel red
bits 8-15pixel green
bits 0-7pixel blue