DOCUMENTATION ERRATA


Technical Reference Manual

p. 28 BrZbBegin() and BrZsBegin()
Values for parameters colour_type and depth_type are described on page 272.

p. 39, 40BrZsPrimitiveCallbackSet()
Both the argument and the result should be of type br_primitive_cbfn, and not br_renderbounds_cbfn.

p. 48, 55, 382
Memory allocator always clears. This is because BRender relies upon the memory allocator to clear the memory it allocates, any replacement allocator should also do this. Therefore the functions BrResAllocate(), BrMemAllocate() and CBFnMemAllocate() can now be relied upon to provide cleared memory.

p. 153Table of flags:
Re: BR_MATF_PERSPECTIVE note that on some platforms this flag will only be supported for specific cases (i.e. on x86 the texture must be of dimension 64x64, 128x128, 256x256, 1024x1024).

p. 154-5 Table showing effects of different combinations of material lighting flags.
Items 17, 18, 19, 20 in column `Pixel set to' indicates a formula including index_base and index_range; index_base is now always taken to be zero, and index_range is now automatically set to the height of the shade table.

p. 164 Example,first line:
br_material BR_CALLBACK * test_callback(_ should read br_material * BR_CALLBACK test_callback(_

p. 180, 183, 187 BrMatrix23{Pre/Post}Rotate()
Rotations about axes: `Clockwise rotationabout the Z-axis' adheres to the right hand rule, i.e. the rotation is clockwise when looking towards positive Z (towards the viewer). Therefore from a viewer's point of view, i.e. when looking towards the XY axes (from Z+) a positive rotation is anti-clockwise.

p. 198-9, 203-4 BrMatrix34Pre/PostRotateXYZ()
Rotations about axes: Change `(looking towards the origin)' to `(looking towards the positive end of the axis)'. Rotations in BRender follow the right hand rule (hitch-hiker's sign), where the thumb is aligned along the axis pointing to the positive end, and the curl of the fingers indicate the direction of a positive rotation (towards the finger-tips).

The following functions are omissions from the Technical Reference Manual

BrFmtScriptMaterialSave()

Description

Load a material from a material script. Note that all maps and tables in a script should be already loaded and registered. If not, this function can be combined with BrMapFindHook() p. 280 and BrTableFindHook()p. 282 to facilitate rapid setup of materials with textures.

Declaration
br_uint_32 BrMftScriptMaterialSave(char *filename, br_material *ptr);

Arguments
const char * filename
Name of destination file for the material script.
br_material * ptr
Material to save.

Effects

Writes the material to a script file. (Any existing file of the same name will be overwritten.)

Result

br_uint_32
Number of materials successfully saved (Success = 1, Failure = 0).

Example

Material scripts are formatted as follows:

See Also

BrFmtScriptMaterialSaveMany(), BrFmtScriptMaterialLoad()(p. 167), BrMaterialAdd()(p. 159).

BrFmtScriptMaterialSavemany()

Description

Save a number of materials to a materials script

Declaration
br_uint_32 BrFmtScriptMaterialSaveMany(const char *filename, br_material ** materials, br_uint_16 num)

Arguments
const char * filename
Name of destination file for the material script.
br_material ** materials
A pointer to an array of pointers to materials.
br_uint_16 num
Maximum number of materials to save.

Effects

Writes the material to a script file. (Any existing file of the same name will be overwritten.)

Result

br_uint_32
Number of materials successfully saved (Success = 1, Failure = 0).

See Also

BrFmtScriptMaterialSave(), BrFmtScriptMaterialLoadMany()(p. 168), BrMaterialAdd()(p. 159).

A general point about parameters

Many functions' parameters have now been upgraded to 32-bit integers from 16-bit ones. Furthermore, signed integers have replaced many arguments that were previously unsigned. This is for consistency and to avoid explicit conversions. For instance, width and height arguments to br_pixelmap operations have changed from br_uint_16 to br_int_32.

BRender Library Naming Conventions

All core BRender libraries have names of the following format BRxxyyyy.LIB where xx describes the contents of the library, DB=DataBase, FM=ForMat, FW=FrameWork, MT=Maths, IO=Input/Output, PM=PixelMap and ST=STandard.

The yyyy component refers to the compiler method of arithmetic and calling convention; BFR=Borland Floating-point, BXR= Borland fiXed-point, MFR=Microsoft Floating-point, MXR=Microsoft fiXed-point, WFRR=Watcom Floating-point Register-calling, WXRR=Microso ft fiXed-point Register-calling,WFRS=Watcom Floating-point Stack-calling, WXRS=Microsoft fiXed-point Stack-calling.

Just in case you are wondering the BR stands for BRender and the R's are to tell us that these are release versions of the libraries.
The various DOS extenders supported by BRender require libraries, the generic parts of this support are in files named DOSIOxxx where the xxx describes the compiler and calling convention as above (with out X/F since these are independent of arithmetic). Platform/extender specific libraries are as follows, HSTxxyyy.LIB where the xx refers to the platform/extender 4G=DOS4GW, PL=Phar Lapp, PP=Power Pack, WN=Windows, and X3=X-32VM.

The yyy refers to the compiler and calling conventions (see above).

Please look in the SAMPLES directory and at the tutorial programs for sample makefiles.

Tutorial Guide

Please note that the program listings in the Tutorial Guide have been superceded by those in the Installation Guide, and those on the Tutorial Programs Disk.

p.13
The translation matrices have 1s across the top row, instead these should be along the leading diagonal.

p.77 figure 39
The lighting values on the left of the `Shade Table' should be in the range [0,63] rather that [0,64].

p.94
The line (1):
texconv gold.gif -n gold -c BR_PMT_INDEX_8 -Q std.pal -o gold8.pix
should read (2):
texconv gold.gif -n gold -Q std.pal -o gold8.pix
The top line will convert a true colour file to an 8-bit file, then quantize the 8-bit file to the std.pal. There is an implicit conversion in the quantization, and the extra step can lead to poor results (approximating an approximation). This misuse of t he command may appear else where in the manual.

Tutorial Programs

All programs have had the arguments to `main' removed, they were unneccesary, and caused `unreferenced variable' warnings on some compilers.

V1.2.1 of BRender now takes origins of destination pixelmaps into account, when rendering a scene. The following lines have been added to each tutorial program:
back_buffer->origin_x=back_buffer->width/2;
back_buffer->origin_y=back_buffer->height/2;

The programs that use 15 bit graphics (#5,6,7,8,10) have had the following changes:
DOSGfxBegin("VESA,W:320,H:200,B:15") has been replaced by the more generic DOSGfxBegin("VESA,B:15").

These programs have had all references to palettes removed; palettes are not necessary in 15 bit. (They would have been ignored, the code was redundant.)