BRender x86 Installation Guide:Appendices: Program Listings and Errata :Documentation Errata
Next|Prev|Up
Technical Reference Manual
BrFmtScriptMaterialSave()
BrFmtScriptMaterialSaveMany()
A general point about parameters
BRender Library Naming Conventions
Tutorial Guide
Tutorial Programs

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, 40 BrZsPrimitiveCallbackSet()

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

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. 153 Table 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 6464, 128128, 256256, 10241024).

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 TRM.


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()280 and BrTableFindHook()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() (below), BrFmtScriptMaterialLoad(167), BrMaterialAdd(159).


BrFmtScriptMaterialSaveMany()

Description:
Save a number of materials to a material 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

Return the number of materials saved successfully.

See Also:
BrFmtScriptMaterialSave() (above), BrFmtScriptMaterialLoadMany(168), BrMaterialAdd(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 be_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=Microsoft 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 the 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.)


Generated with
CERN WebMaker