BlitPixie API

BlitPixie Logo

"fairie magic" written by Anders F Björklund <afb@algonet.se>

Routines | Platforms | Using BlitPixie

Routines

Currently the BlitPixie family of blitters consists of :

BlitPixieClear
A filling/clearing blitter, for erasing with a single color.
BlitPixieRect
A straight rect blitter, optimized for copying large blocks.
BlitPixieDoubleRects
A specialized scrolling blitter, optimized for joining two unaligned blocks to the screen.
BlitPixieFlip
A horizontal-flipping (while copying) blitter.
BlitPixieColorkey
A color-keyed blitter, using a certain pixel color for transparency. Not recommended.
BlitPixieMask
A masking blitter, using a separate B/W pixel mask to allow for transparency.
BlitPixiePartialMask
A variant of the masking blitter, allowing non-clear portions in the sprite image.
BlitPixieMaskCollision
Checks for collisions between two pixel masks.
BlitPixieRLE
A run-length-encoding blitter, using sprites pre-encoded to RLE for speed and size.
BlitPixieRLEClipped
A variant of the RLE blitter, allowing sprites that must be clipped.
BlitPixieRLECollision
Checks for collisions between two RLE encoded sprites.
BlitPixieRLECompiler
Encodes pixel-masked sprites to RLE token encoding.
BlitPixieTranslucent
Translucent blending blitter.
BlitPixieTranslucentMask
Translucent blending blitter, with a separate B/W mask.
BlitPixieTranslucentRLE
Translucent blending blitter, for RLE encoded sprites.
BlitPixieAlpha
Alpha channel blending blitter.
Experimental Blitters :
BlitPixieBlitClear
A cache-optimized "blit and clear to single color" combined blitter.
BlitPixieBlitErase
A cache-optimized "blit and erase with background" combined blitter.
BlitPixieBlitClearDirtyRects
BlitPixieBlitEraseDirtyRects
Like the above, but with a zero-overdraw "dirty rect" matrix.
BlitPixieDoubled
A pixel-doubling blitter, for slower computers or VGA wannabees.
BlitPixieRotoZoomer
A 360° rotating and zooming/scaling blitter.
BlitPixieScale
A scaling blitter.
Only for 680X0 :
BlitPixieCodeCompiler
A sprite compiler, generates 68k code to draw masked pixels only.
BlitPixieAllBit
Versions of BlitPixieRect, BlitPixieMask and BlitPixiePartialMask that works in depths below 8 bits.

Routines | Platforms | Using BlitPixie

Platforms

The blitters come in one or several of four versions:

Motorola 680x0 assembly (68020 or better)
PowerPC assembly (601 or better)
Intel x86 assembly (not yet)
Generic C version (unoptimized)

Supported compilers:

Metrowerks CodeWarrior 9+ / Pro
Apple MPW
THINK C

The assembly versions use CodeWarrior's inline assembly, with some #defines to make stuff more readable.
The inline assembly is separated to stand-alone assembler files for MPW's assemblers automatically, using a script.

Shared libraries are supplied for use by all environments.
Note: They are supposed to be linked into your application, not copied to the System folder.

Routines | Platforms | Using BlitPixie

Using BlitPixie

Parameters

The blitters commonly accept a baseAddr which is a pointer to the start of pixel memory, and a rowBytes which is the offset in bytes from one line of pixels to the next.

Pointer parameters are declared as unsigned char * (UInt8*), and integer parameters as unsigned long (UInt32). Some integers like width and height are given as unsigned short (UInt16).

Depths

The blitter routines work in one of the following bit depths:

Bits per pixel Bytes per pixel Pointer type Colors
8 1 unsigned char 256 Colors
16 2 unsigned short Thousands
32 4 unsigned long Millions

Bits per pixel	Bytes per pixel	Pointer type	Colors
8	1	unsigned char	256 Colors
16	2	unsigned short	Thousands
32	4	unsigned long	Millions

Other pixel depths, such as 1,2,4 or 24 bits are not supported (except with BlitPixieAllBit on the 68k). Pixel conversions are not supported at all, the routines expect Macintosh byte ordering. Definitions of the pixel format can be found in the file BlitPixiePixelFormat.h

To access the pixel memory on the 68k, the processor should be put in 32-bit mode (instead of 24-bit mode) if it isn't already and the pixel map so requires. This can be checked by using PixMap32Bit and changed using SwapMMUMode. Or always use 32-bit mode... (which is the case on the PowerPC)

Compiled Sprites

The sprite compiler converts a pixel mask into a set of 68k assembly instructions (returned as a function ptr), that will draw the masked sprite using the image data when you call it.

NOTE: This function obviously performs no clipping, so be careful.

RLE Sprites

The Run-Length-Encoding format is designed for:

Fast clipping (the linestart tokens)
Alignment (all pixel data is 4-byte aligned)
Fast drawing (repeated pixels are stored as 4-byte only)
All depths (offsets are in bytes)

All RLE tokens are 4 bytes, the first byte is the token type and the next three is the token count. After the token can additional follow extra data, see below table, but the data is always a multiple of 4 bytes wide.

typedef unsigned long       TokenDataType;
#define kTokenShift         24
#define kCountMask          0x00FFFFFFL

Token	Value	Count	Extra Data
`kEndShapeToken`	`00`	always zero	-
`kLineStartToken`	`01`	offset to next linestart token	-
`kDrawPixelsToken`	`02`	bytes to draw	count bytes of pixel data + 0-3 bytes of padding to align to next 4-byte boundary
`kSkipPixelsToken`	`03`	bytes to skip	-
`kSingleColorToken`	`04`	bytes to fill	4 bytes (1/2/4 pixels) to fill repeatedly with

Example:

kLineStartToken #12
- kSkipPixelsToken #12
- kDrawPixelsToken #8 $FF00FF00FF00FF00
kLineStartToken #16
- kSkipPixelsToken #16
- kDrawPixelsToken  #4 $FF00
- kSingleColorToken #20 $0000
- kDrawPixelsToken  #4 $FF00
kEndShapeToken #0

Routines | Platforms | Using BlitPixie

Last updated on 00-08-05 by afb.