br_pixelmap

Fill a pixel map with a given value.

void BrPixelmapFill(br_pixelmap* dat, br_uint_32 colour)

br_pixelmap * dat

A pointer to the pixel map to be filled.

br_uint_32 colour

Value to set each pixel to.

`BrPixelmapRectangleFill()`

Fill a rectangular window in a pixel map with a given value.

void BrPixelmapRectangleFill(br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h, br_uint_32 colour)

A pointer to the destination pixel map.

br_int_16 x,y

Co-ordinates of the rectangle's top left corner.

br_uint_16 w,h

Rectangle width and height (in pixels).

br_uint_32 colour

Value to set each pixel to.

br_int_16 x,y;
br_uint_16 w,h;
br_pixelmap *offscreen;
...
BrPixelmapRectangleFill(offscreen,x,y,w,h,0);

`BrPixelmapLine()`

Draw a line in a pixel map between (x1,y1) and (x2,y2), clipping it to the edges of the pixel map if necessary.

void BrPixelmapLine(br_pixelmap* dst, br_int_16 x1, br_int_16 y1, br_int_16 x2, br_int_16 y2, br_uint_32 colour)

A pointer to the destination pixel map.

br_int_16 x1,y1,x2,y2

Co-ordinates of the line's endpoints.

br_uint_32 colour

Value to set each pixel in the line to.

`BrPixelmapPixelSet()`

Set a pixel to a given value.

void BrPixelmapPixelSet(br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_32 colour)

A pointer to the destination pixel map.

br_int_16 x,y

Pixel co-ordinates.

br_uint_32 colour

Pixel value.

`BrPixelmapPixelGet()`

Get the value of a particular pixel

br_uint_32 BrPixelmapPixelGet(const br_pixelmap* src, br_int_16 x, br_int_16 y)

const br_pixelmap * src

A pointer to the source pixel map from which to read the pixel.

br_int_16 x,y

Pixel co-ordinates.

Some device oriented pixel maps may not support read operations.

br_uint_32 colour

Pixel value. If the point is off-screen, zero will be returned.

Remarks:

`BrPixelmapText()`

Write a string into a pixel map in a given font.

void BrPixelmapText(br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_32 colour, const br_font* font, const char* text)

A pointer to the destination pixel map.

br_int_16 x,y

Co-ordinates of text's top left corner.

br_uint_32 colour

Value to set each text pixel to.

const br_font * font

A pointer to a BRender font, or Null for the default font.

The following pointers are available:

BrFontFixed3x5

BrFontProp4x6

BrFontProp7x9

See brfont.h for precise declaration.

const char * text

A string.

br_uint_32 colour;
br_pixelmap *pmap;
...
BrPixelmapText(pmap,0,0,colour,BrFontProp7x9,"Example text...");

`BrPixelmapTextF()`

Write a `printf' formatted string into a pixel map in a given font. The function will accept format strings and arguments just as for the standard printf() function.

void BrPixelmapTextF(br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_32 colour, const br_font* font, const char* fmt, ...)

A pointer to the destination pixel map.

br_int_16 x, y

Co-ordinates of text's top left corner.

br_uint_32 colour

Value to set each text pixel to.

const br_font * font

A pointer to a BRender font, or Null for the default font.

The following pointers are available:

BrFontFixed3x5

BrFontProp4x6

BrFontProp7x9

See brfont.h for precise declaration.

const char * fmt

A format string (as for printf()).

br_uint_32 colour;
br_pixelmap *pmap;
...
BrPixelmapTextF
(	pmap,0,0,255,NULL,"Frames/Sec = %16g Polys/Sec = %16g"
,	TIMING_FRAMES/((end_time-start_time)/(double)CLOCK_RATE)
,	total_faces	/((end_time-start_time)/(double)CLOCK_RATE)
);

`BrPixelmapTextWidth()`

Find the width of a string for a given font and pixel map.

br_uint_16 BrPixelmapTextWidth(const br_pixelmap* dst, const br_font* font, const char* text)

const br_pixelmap * dst

A pointer to a pixel map.

const br_font * font

A pointer to a BRender font, or Null for the default font.

const char * text

A string.

br_uint_16

Returns the string width in pixels. If the text argument is Null, the width of one character is returned.

BrPixelmapText()277

`BrPixelmapTextHeight()`

Find the height of a font for a given pixel map.

br_uint_16 BrPixelmapTextHeight(const br_pixelmap* dst, const br_font* font)

const br_pixelmap * dst

A pointer to a pixel map.

const br_font * font

A pointer to a BRender font, or Null for the default font.

Returns the font height in pixels.

BrPixelmapText()277

Copy/Assign

The br_pixelmap272 structure should not be copied by structure assignment. Copies should only be made via construction. However, the pixels may be copied, in whole or in part using the following functions.

`BrPixelmapCopy()`

Copy the data in one pixel map to another. The source and destination pixel maps must have the same type and dimensions.

void BrPixelmapCopy(br_pixelmap* dst, const br_pixelmap* src)

A pointer to the destination pixel map.

const br_pixelmap * src

A pointer to the source pixel map.

br_pixelmap *offscreen, *backdrop;
...
BrPixelmapCopy(offscreen, backdrop);

`BrPixelmapRectangleCopy()`

Copy a rectangular window from one pixel map to another.

void BrPixelmapRectangleCopy (br_pixelmap* dst, br_int_16 dx, br_int_16 dy, const br_pixelmap* src, br_int_16 sx,  br_int_16 sy, br_uint_16 w, br_uint_16 h)

Colour or texture maps and shade tables must be added to the registry if they are involved in rendering a scene. They should not be modified during rendering.

A pointer to the destination pixel map.

br_int_16 dx,dy

Co-ordinates of the destination rectangle's top left corner.

const br_pixelmap * src

A pointer to the source pixel map.

br_int_16 sx,sy

Co-ordinates of the source rectangle's top left corner.

br_uint_16 w,h

Rectangle width and height (in pixels).

Access & Maintenance

Colour maps and shade tables that have been added to the registry may be accessed by BRender during rendering.

If any changes are made to colour maps or shade tables involved in rendering, they must be updated before the next rendering in which they are involved.

Note that while texture maps and shade tables are pixel maps, the reverse does not apply. A pixel map is only a texture map by virtue of being added to the registry as such. Similarly with a shade table. Most importantly, a pixel map cannot be both! A texture map must be removed from the registry for it to become just a pixel map, and only then could it be added as a shade table. The same applies with roles interchanged. Note that this just applies to the instance of the br_pixelmap272 data structure, not to the memory that holds the pixel data. Therefore it is quite valid to have a texture map and shade table sharing the same pixel memory (not that it is easy to envisage a useful effect of doing so).

`BrMapAdd()`

Add a texture map to the registry, updating it as necessary. All texture maps must be added to the registry before they are subsequently involved in rendering.

br_pixelmap* BrMapAdd(br_pixelmap* pixelmap)

A pointer to a texture map.

Returns a pointer to the added texture map, else Null if unsuccessful.

BrMapUpdate()282, BrMapAddMany()282, BrPixelmapLoad()295, BrMapFind()289, BrMapRemove()282.

`BrMapAddMany()`

Add a number of texture maps to the registry, updating them as necessary.

br_uint_32 BrMapAddMany(br_pixelmap* const* pixelmaps, int n)

A pointer to an array of pointers to texture maps.

int n

Number of texture maps to add to the registry.

Returns the number of texture maps added successfully.

BrMapUpdate()282, BrMapAdd()281, BrMapRemove()282, BrMapRemoveMany()283

`BrMapUpdate()`

Update a texture map.

void BrMapUpdate(br_pixelmap* pixelmap, br_uint_16 flags)

Texture map update flags. In general, BR_MAPU_ALL should be used.

A pointer to a texture map.

br_uint_16 flags

BrMapAdd()281.

`BrMapRemove()`

Remove a texture map from the registry.

br_pixelmap* BrMapRemove(br_pixelmap* pixelmap)

A pointer to a texture map.

Returns a pointer to the item removed.

BrMapAdd()281

`BrMapRemoveMany()`

Remove a number of texture maps from the registry.

br_uint_32 BrMapRemoveMany(br_pixelmap* const* pixelmaps, int n)

A pointer to an array of pointers to texture maps.

int n

Number of texture maps to remove from the registry.

Returns the number of texture maps removed successfully.

BrMapAddMany()282

`BrTableAdd()`

Add a shade table to the registry, updating it as necessary. All shade tables must be added to the registry before they are used subsequently.

br_pixelmap* BrTableAdd(br_pixelmap* pixelmap)

A pointer to a shade table.

Returns a pointer to the added shade table, else Null if unsuccessful.

BrTableUpdate()284, BrTableAddMany()283, BrPixelmapLoad()295, BrTableFind()292, BrTableRemove()284

`BrTableAddMany()`

Add a number of shade tables to the registry, updating them as necessary.

br_uint_32 BrTableAddMany(br_pixelmap* const* pixelmaps, int n)

A pointer to an array of pointers to shade tables.

int n

Number of shade tables to add to the registry.

Returns the number of shade tables added successfully.

BrTableUpdate()284, BrTableAdd()283, BrTableRemove()284, BrTableRemoveMany()284

`BrTableUpdate()`

Update a shade table.

void BrTableUpdate(br_pixelmap* pixelmap, br_uint_16 flags)

Shade table update flags. In general, BR_TABU_ALL should be used.

A pointer to a shade table.

br_uint_16 flags

BrTableAdd()283.

`BrTableRemove()`

Remove a shade table from the registry.

br_pixelmap* BrTableRemove(br_pixelmap* pixelmap)

A pointer to a shade table.

Returns a pointer to the shade table removed.

BrTableAdd()283

`BrTableRemoveMany()`

Remove a number of shade tables from the registry.

br_uint_32 BrTableRemoveMany(br_pixelmap* const* pixelmaps, int n)

A pointer to an array of pointers to shade tables.

int n

Number of shade tables to remove from the registry.

Returns the number of shade tables removed successfully.

Pixel maps may be freely and multiply referenced. Once added to the registry as a texture map or shade table, there are certain restrictions, but they may still be multiply referenced. Maps and tables must have been added to the registry if they will be involved in rendering. Texture maps and shade tables must be maintained while they are in the registry or being referenced.

BrTableAddMany()283

Referencing & Lifetime

Initialisation

The structure is initialised by the various construction functions. Pixel maps should not be created or initialised by any other means.

Construction & Destruction

Apart from platform specific functions, pixel maps should only be constructed by the following BRender functions. Destruction should naturally be performed by the corresponding `free' function, usually BrPixelmapFree()287. Note that texture maps and shade tables should be removed from the registry before destruction.

`BrPixelmapAllocate()`

Allocate a new pixel map.

br_pixelmap* BrPixelmapAllocate(br_uint_8 type, br_uint_16 w, br_uint_16 h, void* pixels, int flags)

A pointer to an existing block of memory. If Null, the pixel memory is allocated automatically using BrResAllocate()48.

br_uint_8 type

Pixel map type.

br_uint_16 w

Width in pixels.

br_uint_16 h

Height in pixels.

void * pixels

The calculation obtaining the minimum size required for the block of memory is non-obvious. It is row_bytes*h., and row_bytes is not simply w*bits-per-pixel/8. To determine row_bytes, it is probably simplest to call this function with a dummy, non-Null pointer (address of an automatic, say), and record the value of row_bytes returned in the br_pixelmap272 (free it immediately afterwards). The memory pointed to by pixels is not accessed by this function.

int flags

Supply either BR_PMAF_NORMAL or BR_PMAF_INVERTED. If the latter, the function will automatically set the pixels member of the returned pixel map (whether supplied or not) to be at the start of the final row of pixel map memory (row_bytes is negative).

Returns a pointer to the new pixel map, or Null if unsuccessful.

`BrPixelmapAllocateSub()`

Allocate a pixel map as part of an existing pixel map. The new pixel map is clipped to the existing pixel map.

br_pixelmap* BrPixelmapAllocateSub(br_pixelmap* pm, br_uint_16 x, br_uint_16 y, br_uint_16 w, br_uint_16 h)

br_pixelmap * pm

A pointer to an existing pixel map.

br_uint_16 x,y

Co-ordinates of the top left of the new pixel map in the existing pixel map.

br_uint_16 w,h

Width and height of the new pixel map.

The effective origin is set that of the existing pixel map.

Returns a pointer to the new pixel map, or Null if unsuccessful.

Remarks:

`BrPixelmapMatch()`

Given a pixel map, allocate either a depth buffer or an off-screen colour buffer with the same dimensions.

br_pixelmap* BrPixelmapMatch(const br_pixelmap* src, int match_type)

const br_pixelmap * src

A pointer to the source pixel map.

int match_type

The type of matching pixel map required.

Returns a pointer to the matching pixel map.

`BrPixelmapClone()`

Create a pixel map of the same type and dimensions and copy the pixel data.

br_pixelmap* BrPixelmapClone(const br_pixelmap* src)

const br_pixelmap * src

A pointer to the source pixel map.

Returns a pointer to the new pixel map.

br_pixelmap *image, *working_copy;
...
image = BrPixelmapLoad("backdrop.pix");
working_copy = BrPixelmapClone(image);

`BrPixelmapFree()`

Deallocate a pixel map and any associated memory.

void BrPixelmapFree(br_pixelmap* pmap)

br_pixelmap * pmap

A pointer to a pixel map.

Supplementary

`BrPixelmapPixelSize()`

Find the pixel size for a given pixel map.

br_uint_16 BrPixelmapPixelSize(const br_pixelmap* pm)

const br_pixelmap * pm

A pointer to a pixel map.

br_uint_16

Returns the size of each pixel, in bits.

`BrPixelmapChannels()`

Find the channels available for a given pixel map.

br_uint_16 BrPixelmapChannels(const br_pixelmap* pm)

const br_pixelmap * pm

A pointer to a pixel map.

br_uint_16

Returns a mask giving the available channels, being a combination of the following bit value symbols:

`BrMapCount()`

Count the number of registered texture maps whose names match a given search pattern. The search pattern can include the standard wild cards `*' and `?'.

br_uint_32 BrMapCount(const char* pattern)

Search pattern.

Returns the number of texture maps matching the search pattern.

BrMapEnum()289, BrMapFind()289

`BrMapEnum()`

Calls a call-back function for every texture map matching a given search pattern. The call-back is passed a pointer to each matching item, and its second argument is an optional pointer supplied by the user. The search pattern can include the standard wild cards `*' and `?'. The call-back itself returns a br_uint_32348 value. The enumeration will halt at any stage if the return value is non-zero.

Declaration:

br_uint_32 BrMapEnum(const char* pattern, br_map_enum_cbfn* callback, void* arg)

Arguments:

const char * pattern

Search pattern.

br_map_enum_cbfn * callback

A pointer to a call-back function.

void * arg

An optional argument to pass to the call-back function.

Result:

br_uint_32

Returns the first non-zero call-back return value, or zero if all matching texture maps are enumerated.

Example:

br_uint_32 BR_CALLBACK test_callback(br_pixelmap* map, void* arg)
{	br_uint_32 count;
...
	return(count);
}
...
{	br_uint_32 enum;
...
	enum = BrMapEnum("map",&test_callback,NULL);
}

`BrMapFind()`

Find a texture map in the registry by name. A call-back function can be setup to be called if the search is unsuccessful. The search pattern can include the standard wild cards `*' and `?'.

br_pixelmap* BrMapFind(const char* pattern)

Search pattern.

Returns a pointer to the texture map if found, otherwise Null. If a call-back exists and is called, the call-back's return value is returned.

BrMapFindHook()290, BrMapFindMany()290

`BrMapFindMany()`

Find a number of texture maps in the registry by name. The search pattern can include the standard wild cards `*' and `?'.

br_uint_32 BrMapFindMany(const char* pattern, br_pixelmap** pixelmaps, int max)

Search pattern.

br_pixelmap ** pixelmaps

A pointer to an array of pointers to texture maps.

int max

Maximum number of texture maps to find.

Returns the number of texture maps found. The pointer array is filled with pointers to the found texture maps.

BrMapFind()289, BrMapFindHook()290

`BrMapFindHook()`

Functions to set up a call-back.

br_map_find_cbfn* BrMapFindHook(br_map_find_cbfn* hook)

br_map_find_cbfn * hook

A pointer to a call-back function.

Effects:

If BrMapFind()289 is unsuccessful and a call-back has been set up, the call-back is passed the search pattern as its only argument. The call-back should then return a pointer to a substitute or default texture map.

For example, a call-back could be set up to return a default texture map if the desired texture map cannot be found in the registry.

The function BrMapFindFailedLoad()291 is provided and will probably be sufficient in many cases.

Result:

br_map_find_cbfn *

Returns a pointer to the old call-back function.

Example:

br_map BR_CALLBACK * test_callback(char* pattern)
{	br_map* default_map;
...
	return(default_map);
}
...
{	br_map* map;
...
	BrMapFindHook(&test_callback);
	map = BrMapFind("non_existent_map");
}

See Also:

BrMapFindFailedLoad()291

`BrMapFindFailedLoad()`

This function is provided as a suitable function to supply to BrMapFindHook()290.

Declaration:

br_pixelmap* BrMapFindFailedLoad(const char* name)

Arguments:

const char * name

The name supplied to BrMapFind()289.

Effects:

Attempts to load the texture map from the filing system using name as the filename. Searches in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). If successful, sets this name as the identifier of the loaded texture map and adds the texture map to the registry.

Result:

br_pixelmap *

Returns a pointer to the texture map, if found, else Null.

Example:

BrMapFindHook(BrMapFindFailedLoad);

`BrTableCount()`

Count the number of registered shade tables whose names match a given search pattern. The search pattern can include the standard wild cards `*' and `?'.

br_uint_32 BrTableCount(const char* pattern)

Search pattern.

Returns the number of shade tables matching the search pattern.

BrTableEnum()292, BrTableFind()292

`BrTableEnum()`

Calls a call-back function for every shade table matching a given search pattern. The call-back is passed a pointer to each matching shade table, and its second argument is an optional pointer supplied by the user. The search pattern can include the standard wild cards `*' and `?'. The call-back itself returns a br_uint_32348 value. The enumeration will halt at any stage if the return value is non-zero.

Declaration:

br_uint_32 BrTableEnum(const char* pattern, br_table_enum_cbfn* callback, void* arg)

Arguments:

const char * pattern

Search pattern.

br_table_enum_cbfn * callback

A pointer to a call-back function.

void * arg

An optional argument to pass to the call-back function.

Result:

br_uint_32

Returns the first non-zero call-back return value, or zero if all matching shade tables are enumerated.

Example:

br_uint_32 BR_CALLBACK test_callback(br_pixelmap* table, void* arg)
{	br_uint_32 count;
...
	return(count);
}
...
{	br_uint_32 enum;
...
	enum = BrTableEnum("Table",&test_callback,NULL);
}

`BrTableFind()`

Find a shade table in the registry by name. A call-back function can be setup to be called if the search is unsuccessful. The search pattern can include the standard wild cards `*' and `?'.

br_pixelmap* BrTableFind(const char* pattern)

Search pattern.

Returns a pointer to the shade table if found, otherwise Null. If a call-back exists and is called, the call-back's return value is returned.

BrTableFindHook()293, BrTableFindMany()293

`BrTableFindMany()`

Find a number of shade tables in the registry by name. The search pattern can include the standard wild cards `*' and `?'.

br_uint_32 BrTableFindMany(const char* pattern, br_pixelmap** pixelmaps, int max)

Search pattern.

br_pixelmap ** pixelmaps

A pointer to an array of pointers to shade tables.

int max

Maximum number of shade tables to find.

Returns the number of shade tables found. The pointer array is filled with pointers to the found shade tables.

BrTableFind()292, BrTableFindHook()293

`BrTableFindHook()`

Functions to set up a call-back. If BrTableFind()292 is unsuccessful and a call-back has been set up, the call-back it is passed the search pattern as its only argument. The call-back should then return a pointer to a substitute or default shade table.

For example, a call-back could be set up to return a default shade table if the desired shade table cannot be found in the registry.

The function BrTableFindFailedLoad()294 is provided and will probably be sufficient in many cases.

Declaration:

br_table_find_cbfn* BrTableFindHook(br_table_find_cbfn* hook)

Arguments:

br_table_find_cbfn * hook

A pointer to a call-back function.

Result:

br_table_find_cbfn *

Returns a pointer to the old call-back function.

Example:

br_table BR_CALLBACK * test_callback(char* pattern)
{	br_table* default_table;
...
	return(default_table);
}
...
{	br_table* table;
...
	BrTableFindHook(&test_callback);
	table = BrTableFind("non_existent_table");
}

See Also:

BrTableFindFailedLoad()294

`BrTableFindFailedLoad()`

This function is provided as a suitable function to supply to BrTableFindHook()293.

Declaration:

br_pixelmap* BrTableFindFailedLoad(const char* name)

Arguments:

const char * name

The name supplied to BrTableFind()292.

Effects:

Attempts to load the shade table from the filing system using name as the filename. Searches in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). If successful, sets this name as the identifier of the loaded shade table and adds the shade table to the registry.

Result:

br_pixelmap *

Returns a pointer to the shade table, if found, else Null.

Example:

BrTableFindHook(BrTableFindFailedLoad);

Import & Export

`BrPixelmapFileCount()`

Locate a given file and count the number of pixel maps in it.

br_uint_32 BrPixelmapFileCount(const char* filename, br_uint_16* num)

Searches for filename, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). If a file is found, will count the number of pixel maps stored in it.

const char * filename

Name of the file containing the pixel maps to count.

br_uint_16 * num

Pointer to the variable in which to store the number of pixel maps counted in the file. If Null, the file will still be located and appropriate success returned, but no count will be made.

Effects: