BRL.Pixmap:

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.

Functions Summary

ClearPixels	Clear a pixmap.
ConvertPixmap	Convert pixel format of a pixmap.
CopyPixmap	Copy a pixmap.
CreatePixmap	Create a pixmap.
CreateStaticPixmap	Create a pixmap with existing pixel data.
LoadPixmap	Load a pixmap.
MaskPixmap	Mask a pixmap.
PixmapFormat	Get pixmap format.
PixmapHeight	Get pixmap width.
PixmapPitch	Get pixmap pitch.
PixmapPixelPtr	Get pixmap pixels.
PixmapWidth	Get pixmap width.
PixmapWindow	Create a pixmap window.
ReadPixel	Read a pixel from a pixmap.
ResizePixmap	Resize a pixmap.
WritePixel	Write a pixel to a pixmap.
XFlipPixmap	Flip a pixmap horizontally.
YFlipPixmap	Flip a pixmap vertically.

Types Summary

TPixmap	The Pixmap type.
TPixmapLoader	Abstract base type for pixmap loaders.

Functions

Function ClearPixels( pixmap:TPixmap,argb=0 )

Description

Clear 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-31	pixel alpha
bits 16-23	pixel red
bits 8-15	pixel green
bits 0-7	pixel blue

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

Function CopyPixmap:TPixmap( pixmap:TPixmap )
Returns	A new pixmap object.
Description	Copy a pixmap.

Function CreatePixmap:TPixmap( width,height,format,align_bytes=4 )

Returns

A new pixmap object of the specified width and height.

Description

Create a pixmap.

Information

format should be one of the following:

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.

Format	Description
PF_A8	8 bit alpha
PF_I8	8 bit intensity
PF_RGB888	24 bit big endian RGB
PF_BGR888	24 bit little endian RGB
PF_RGBA8888	32 bit big endian RGB with alpha
PF_BGRA8888	32 bit little endian RGB with alpha

Function CreateStaticPixmap:TPixmap( pixels:Byte Ptr,width,height,pitch,format )
Returns	A new pixmap object that references an existing block of memory.
Description	Create 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 LoadPixmap:TPixmap( url:Object )
Returns	A pixmap object.
Description	Load a pixmap.

Function MaskPixmap:TPixmap( pixmap:TPixmap,mask_red,mask_green,mask_blue )
Returns	A new pixmap object.
Description	Mask a pixmap.
Information	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.

Function PixmapFormat( pixmap:TPixmap )

Returns

The format of the pixels stored in pixmap.

Description

Get pixmap format.

Information

The returned value will be one of:

Format	Description
PF_A8	8 bit alpha
PF_I8	8 bit intensity
PF_RGB888	24 bit big endian RGB
PF_BGR888	24 bit little endian RGB
PF_RGBA8888	32 bit big endian RGB with alpha
PF_BGRA8888	32 bit big endian RGB with alpha

Function PixmapHeight( pixmap:TPixmap )
Returns	The height, in pixels, of pixmap.
Description	Get pixmap width.

Function PixmapPitch( pixmap:TPixmap )
Returns	The pitch, in bytes, of pixmap.
Description	Get 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 PixmapPixelPtr:Byte Ptr( pixmap:TPixmap,x=0,y=0 )
Returns	A byte pointer to the pixels stored in pixmap.
Description	Get pixmap pixels.

Function PixmapWidth( pixmap:TPixmap )
Returns	The width, in pixels, of pixmap.
Description	Get pixmap width.

Function PixmapWindow:TPixmap( pixmap:TPixmap,x,y,width,height )
Returns	A new pixmap object.
Description	Create a pixmap window.
Information	PixmapWindow creates a 'virtual' window into pixmap.

Function ReadPixel( pixmap:TPixmap,x,y )

Returns

A 32 bit pixel value.

Description

Read a pixel from a pixmap.

Information

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

Function ResizePixmap:TPixmap( pixmap:TPixmap,width,height )
Returns	A new pixmap object of the specified width and height.
Description	Resize a pixmap.

Function WritePixel( pixmap:TPixmap,x,y,argb )

Description

Write a pixel to a pixmap.

Information

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

Function XFlipPixmap:TPixmap( pixmap:TPixmap )
Returns	A new pixmap object.
Description	Flip a pixmap horizontally.

Function YFlipPixmap:TPixmap( pixmap:TPixmap )
Returns	A new pixmap object.
Description	Flip a pixmap vertically.

Types

Type TPixmap Extends TData
Description	The Pixmap type.

Fields Summary
capacity , format , height , pitch , pixels , width

Methods Summary
ClearPixels	Clear a pixmap.
Convert	Convert a pixmap.
Copy	Duplicate a pixmap.
Paste	Paste a pixmap.
PixelPtr	Get memory address of a pixel.
ReadPixel	Read a pixel from a pixmap.
Window	Create a virtual window into a pixmap.
WritePixel	Write a pixel to a pixmap.

Functions Summary
Create	Create a pixmap.
CreateStatic	Create a static pixmap.

Field capacity
Description	The capacity, in bytes, of the pixmap, or -1 for a static pixmap.

Field format
Description	The pixel format of the pixmap.

Field height
Description	The height, in pixels, of the pixmap.

Field pitch
Description	The pitch, in bytes, of the pixmap.

Field pixels:Byte Ptr
Description	A byte pointer to the pixmap's pixels.

Field width
Description	The width, in pixels, of the pixmap.

Method ClearPixels( argb )
Description	Clear a pixmap.

Method Convert:TPixmap( format )
Returns	A new TPixmap object in the specified format.
Description	Convert a pixmap.

Method Copy:TPixmap()
Returns	A new TPixmap object.
Description	Duplicate a pixmap.

Method Paste( source:TPixmap,x,y )
Description	Paste a pixmap.

Method PixelPtr:Byte Ptr( x,y )
Returns	A byte pointer to the pixel at coordinates x, y.
Description	Get memory address of a pixel.

Method ReadPixel( x,y )
Returns	The pixel at the specified coordinates packed into an integer.
Description	Read a pixel from a pixmap.

Method Window:TPixmap( x,y,width,height )
Returns	A static pixmap that references the specified rectangle.
Description	Create a virtual window into a pixmap.

Method WritePixel( x,y,argb )
Description	Write a pixel to a pixmap.

Function Create:TPixmap( width,height,format,align=4 )
Returns	A new TPixmap object.
Description	Create a pixmap.

Function CreateStatic:TPixmap( pixels:Byte Ptr,width,height,pitch,format )
Returns	A new TPixmap object.
Description	Create a static pixmap.

Type TPixmapLoader
Description	Abstract base type for pixmap loaders.
Information	To create a new pixmap loader, you should extend TPixmapLoader and implement the LoadPixmap method. To install your pixmap loader, simply create an instance of it using New.

Methods Summary
LoadPixmap	Load a pixmap.

Method LoadPixmap:TPixmap( stream:TStream ) Abstract
Description	Load a pixmap.
Information	This method must be implemented by extending types.

Module Information

Version	1.07
Author	Mark Sibly
License	Blitz Shared Source Code
Copyright	Blitz Research Ltd
Modserver	BRL
History	1.07 Release
History	Added ClearPixels
History	1.06 Release
History	Added new GL compatible pixel formats
History	1.05 Release
History	Added _source:Object field
History	Removed AddPixmapLoader function