OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warptlk3.zip / TOOLKIT / BETA / BOOK / BRENDER.INF (.txt) < prev next >

Wrap

OS/2 Help File | 1995-09-06 | 128.5 KB | 7,439 lines

ΓòÉΓòÉΓòÉ 1. Disclaimer ΓòÉΓòÉΓòÉ Argonaut Technologies Ltd. makes no expressed or implied warranty with respect to the contents of this manual, and assumes no responsibility for any errors or omissions which it may contain. No liability is assumed for any direct, indirect or consequential damages or losses arising in connection with the information or examples described herein Copyright 1995 Argonaut Technologies Ltd. ΓòÉΓòÉΓòÉ 1.1. Trademarks ΓòÉΓòÉΓòÉ 3D Studio is a registered trademark of Autodesk, Inc. Windows, Windows 95, and Windows NT are registered trademarks of Microsoft Corporation. OS/2 is a registered trademark of IBM Corporation. ΓòÉΓòÉΓòÉ 2. 1. Introduction ΓòÉΓòÉΓòÉ BRender is an extremely powerful real-time 3D graphics library, with a comprehensive Application Programming Interface (API), facilitating rapid and intuitive 3D development. ΓòÉΓòÉΓòÉ 2.1. 1.1 Overview ΓòÉΓòÉΓòÉ The libraries have an elegant conceptual design throughout and are, as far as possible, platform independent. In brief, they provide functions and data structures relevant to the following areas: Mathematical primitives, including scalars, angles, quaternions, Euler angles, vectors and matrices, using fixed or floating point numerical representations. Rendering, in a number of styles. Scene picking and elementary collision detection. Hierarchical organisation of objects constituting a scene. Lights, cameras and models. Texture and environment mapping. Efficient handling of items in a 'world database'. File systems, memory management and error handling Typically, a BRender application will perform the following tasks: Initialisation. Importing or generating data, for instance, models, materials and textures. Rendering scenes. Modification of object positions and orientations. User interaction. ΓòÉΓòÉΓòÉ 2.2. 1.2 Actors and Hierarchies ΓòÉΓòÉΓòÉ Models, lights, cameras, bounding boxes and clipping planes are all actors. A scene consists of a tree-structured hierarchy of actors, and is rendered by traversing the tree, beginning at its root. Chapter three describes actors and their associated data structures in detail. The position and orientation of an actor is not given in some absolute coordinate system. Instead, they are relative to the coordinate system of the actor's parent in the hierarchy. In fact, BRender applies a general affine transformation between each actor and each one of its children. As the tree is traversed, the transformations are accumulated. The root of the hierarchy has no parent, and consequently, it is the only actor with an absolute coordinate system. BRender has a dummy actor type, which can be used to assist the layout and organisation of a hierarchy. Invariably, the root of a hierarchy will be a dummy actor. The smallest hierarchy that will produce an actual rendered scene consists of four actors, namely a dummy actor, a model, a camera and a light source. The dummy actor is at the root of the hierarchy, and the model, camera and light are its children. ΓòÉΓòÉΓòÉ 2.3. 1.3 Callbacks ΓòÉΓòÉΓòÉ Callback functions provide a powerful mechanism for customising BRender to suit a particular application or platform. Quite simply, a callback is a pointer to a function which can be changed by the user as and when necessary. When appropriate, BRender uses that pointer to invoke the function. For example, BRender allows a model to have its own custom callback function, which is invoked whenever the model is about to be rendered. The user application can then perform a number of custom tasks associated with the model, before returning control to BRender. ΓòÉΓòÉΓòÉ 2.4. 1.4 Documentation Conventions ΓòÉΓòÉΓòÉ Throughout this manual, syntax, arguments, definitions and example code are in the typewriter font, to distinguish them from normal text. For example, void BrTransformToTransform(br_transform *dest, br_transform *src); or BR_ACTOR_CAMERA The '#' character is used as a wildcard in a number of sections and headings, and usually to refer to a collection of functions with a similar name. For example, BrMatrix34PostRotate# will actually refer to the following three function: BrMatrix34PostRotateX BrMatrix34PostRotateY BrMatrix34PostRotateZ In general, only the public members of BRender data structures are documented. Therefore, care must be taken if instances of those structures are initialised statically. The reader may wish to refer to the relevant BRender header files for the complete structure definitions. ΓòÉΓòÉΓòÉ 3. 2. The Rendering Engine ΓòÉΓòÉΓòÉ BRender's rendering engine performs the following high-level operations: Initialisation Rendering scenes using a Z buffer Picking actors through a given line of sight Elementary collision detection ΓòÉΓòÉΓòÉ 3.1. 2.1 Initialisation ΓòÉΓòÉΓòÉ 2.1.1 Functions 2.1.1.1 BrBegin Syntax void BrBegin(void); Description Initialise BRender. This function must be called before any other BRender functions are used. See also BrEnd 2.1.1.2 BrEnd Syntax void BrEnd(void); Description Exit Brender, freeing its internal resources and memory. See also BrBegin 2.1.2 Z buffer 2.1.2.1 BrZbBegin Syntax void BrZbBegin(br_uint_8 colour_type, br_uint_8 depth_type); Description Initialize the Z-buffer renderer. Arguments colour_type Pixelmap type of buffer to render into. depth_type Pixelmap type of Z-buffer. See also BrZbEnd Pixelmap types (section 3.8.1.2) 2.1.2.2 BrZbEnd Syntax void BrZbEnd(void); Description Close down the Z-buffer renderer. See also BrZbBegin 2.1.2.3 BrZbSceneRender Syntax void BrZbSceneRender(br_actor *world, br_actor *camera, br_pixelmap *colour_buffer, br_pixelmap *depth_buffer); Description Render a scene using the Z-buffer renderer. Arguments world A pointer to the root actor of a scene. camera A pointer to a camera actor. colour_buffer A pointer to the pixelmap to render the scene into. depth_buffer A pointer to the pixelmap to be used as a Z-buffer. It must have the same width and height as the colour buffer. Associated definitions BR_MAX_NAME Maximum length of a BRender identifier. BR_MAX_LIGHTS Maximum number of active lights. BR_MAX_CLIP_PLANES Maximum number of clipping planes. See also br_actor br_camera br_pixelmap 2.1.2.4 BrZbSceneRenderBegin Syntax void BrZbSceneRenderBegin(br_actor *world, br_actor *camera, br_pixelmap *colour_buffer, br_pixelmap *depth_buffer); Description Set up a new scene to be rendered, processing the camera, lights and environment. Arguments world A pointer to the root actor of a scene. camera A pointer to a camera actor. colour_buffer A pointer to the pixelmap to render the scene into. depth_buffer A pointer to the pixelmap to be used as a Z-buffer. See also BrZbSceneRenderAdd BrZbSceneRenderEnd 2.1.2.5 BrZbSceneRenderAdd Syntax void BrZbSceneRenderAdd(br_actor *tree); Description Add a hierarchy of actors to the current rendering. Arguments tree A pointer to an actor hierarchy. See also BrZbSceneRenderBegin BrZbSceneRenderEnd 2.1.2.6 BrZbSceneRenderEnd Syntax void BrZbSceneRenderEnd(void); Description Finish rendering a scene, having begun with BrZbSceneRenderBegin. See also BrZbSceneRenderBegin BrZbSceneRenderAdd 2.1.2.7 BrZbModelRender Syntax void BrZbModelRender(br_actor *actor, br_model *model, br_material *material, br_uint_8 style, int on_screen, int use_custom); Description Render a model actor as part of the current rendering. Arguments actor A pointer to an actor. model A pointer to the actor's model. material A pointer to the actor's material. style The actor's rendering style. on_screen A flag specifying whether the model is either partially or completely on-screen (either OSC_PARTIAL or OSC_ACCEPT). use_custom If non-zero, invoke the models custom callback function. See also Custom model callback functions (section 3.5.3) 2.1.2.8 BrZbSetRenderBoundsCallback Syntax br_renderbounds_cbfn * BrZbSetRenderBoundsCallback(br_renderbounds_cbfn *new_cbfn); Description Set the callback function invoked for each rendered actor. For example, a callback can be set up to log those rectangles in the colour buffer that have been written to (dirty rectangle flagging). Arguments new_cbfn A pointer to the new callback function. Return value Returns a pointer to the old callback function. See also br_renderbounds_cbfn 2.1.2.9 br_renderbounds_cbfn Syntax typedef void BR_CALLBACK br_renderbounds_cbfn(br_actor *actor, br_model *model, br_material *material, br_uint_8 style, br_matrix4 *model_to_screen, br_int_32 bounds[4]); Description Type definition for a callback invoked for each rendered actor. A callback of this nature can perform a number of useful operations, for instance: Dirty rectangle flagging; determining which actors are on-screen from frame to frame; interrupting the renderer and performing custom operations. The BR_CALLBACK macro must be used to ensure compiler compatibility. The following arguments are passed to the callback function. Arguments actor A pointer to the actor just rendered. model A pointer to the actor's model. material A pointer to the actor's material. style The actor's rendering style. model_to_screen A pointer to a matrix giving the transformation from the models space to the screen. bounds An array of X and Y values giving the dimensions of the actor's bounding rectangle on screen. Elements in the array should be indexed with the following definitions: BR_BOUNDS_MIN_X = 0 BR_BOUNDS_MIN_Y = 1 BR_BOUNDS_MAX_X = 2 BR_BOUNDS_MAX_Y = 3 See also BrZbSetRenderBoundsCallback ΓòÉΓòÉΓòÉ 3.2. 2.2 Scene picking ΓòÉΓòÉΓòÉ 2.2.1 Functions 2.2.1.1 BrScenePick2D Syntax int BrScenePick2D(br_actor *world, br_actor *camera, br_pixelmap *viewport, int pick_x, int pick_y, br_pick2d_cbfn *callback, void *arg); Description Traverse a world hierarchy, picking model actors from the scene by casting a ray through a given viewport pixel attached to a given camera. A callback is invoked for each actor whose bounds intersect the ray. If the callback returns a non-zero value, traversal halts. Arguments world A pointer to the root of a world hierarchy. camera A pointer to a camera actor. viewport A pointer to the viewport through which the pick ray passes. pick_x, pick_y Coordinates of viewport pixel through which the pick ray passes. callback A pointer to a pick-2D callback function. arg An optional argument to pass to the callback function. Return value If the callback returns a non-zero value and traversal halts, that value is returned. Otherwise, zero is returned. See also br_pick2d_cbfn BrScenePick3D 2.2.1.2 br_pick2d_cbfn Syntax typedef int BR_CALLBACK br_pick2d_cbfn(br_actor *a, br_model *model, br_vector3 *ray_pos, br_vector3 *ray_dir, br_scalar t_near, br_scalar t_far, void *arg); Description Type definition for a pick-2D callback function. The following arguments are passed to it, for each actor whose bounds intersect the pick ray. The BR_CALLBACK macro must be used to ensure compiler compatibility. Arguments a A pointer the actor. model A pointer to the actor's model. ray_pos A pointer to a vector giving the ray position in the actor's own space. ray_dir A pointer to a vector giving the ray direction in the actor's own space. t_near, t_far The absolute values of the Z coordinates of the near and far bounds intersections, in view space. arg An optional argument passed to the callback. Return value Returns an integer. If it is non-zero, traversal will halt. See also BrScenePick2D 2.2.1.3 BrScenePick3D Syntax int BrScenePick3D(br_actor *world, br_actor *reference, br_bounds *bounds, br_pick3d_cbfn *callback, void *arg); Description Traverse a world hierarchy and invoke a callback function for each model actor whose bounds intersect a given bounds in a given reference actor's space. If the callback returns a non-zero value, traversal halts. Arguments world A pointer to the root of a world hierarchy. reference A pointer to the reference actor. bounds A pointer to a bounds structure. callback A pointer to a pick-3D callback function. arg An optional argument to pass to the callback function. Return value If the callback returns a non-zero value and traversal halts, that value is returned. Otherwise, zero is returned. See also br_pick3d_cbfn BrScenePick2D 2.2.1.4 br_pick3d_cbfn Syntax typedef int BR_CALLBACK br_pick3d_cbfn(br_actor *a, br_model *model, br_matrix34 *transform, br_bounds *bounds, void *arg); Description Type definition for a pick-3D callback function. The following arguments are passed to it, for each bounds intersection. The BR_CALLBACK macro must be used to ensure compiler compatibility. Arguments a A pointer the actor. model A pointer to the actor's model. transform A pointer to a matrix transformation from the intersecting actor to the reference actor. bounds A pointer to the original bounds given to BrScenePick3D. arg An optional argument passed to the callback. Return value Returns an integer. If it is non-zero, traversal will halt. See also BrScenePick3D ΓòÉΓòÉΓòÉ 4. 3. The World Database ΓòÉΓòÉΓòÉ BRender renders actor hierarchies. This chapter describes the data structures which constitute the different actor types, and the functions provided to support them. The topics covered include: Actors Lights Cameras Clipping planes Models Custom model callback functions Materials Texture maps Environment maps Pixelmaps Shade tables Colour Transforms ΓòÉΓòÉΓòÉ 4.1. 3.1 Actors ΓòÉΓòÉΓòÉ 3.1.1 Datatypes 3.1.1.1 br_actor Structure typedef struct br_actor { br_actor *next; br_actor **prev; br_actor *children; br_actor *parent; br_uint_16 depth; br_uint_8 type; char *identifier; br_model *model; br_material *material; br_uint_8 render_style; br_transform t; void *type_data; } br_actor; Description BRender represents everything in a 3D world as a tree-structured hierarchy of actors. Of the seven possible types of actor, the three most important are models, cameras, and lights. Some actors have extra type-specific data attached to them. Members next References the next actor in a linked list of siblings. prev References the previous actor in a linked list of siblings. children References a child of this actor. parent References the parent of this actor. depth The depth of this actor from the root of the hierarchy. This value is maintained by BRender automatically. type Actor type (see section 3.1.1.2). *identifier Actor name. model If the actor is a model, this points to the relevent model structure. If NULL, the parental model is used. The root actor inherits a default model (a cube). material If the actor is a model, this points to its default material, assigned to faces which do not specify a material explicitly. The default is defined per-actor to make model re-use more convenient. If NULL, the default material is inherited from the parent actor. The root actor inherits a default material (flat-shaded grey). render_style Rendering style (see section 3.1.1.3). t The transformation between this actor and its parent. Transformations are accumulated down the actor hierarchy, and thus the transformation applied to the parent is also applied to this actor. type_data A pointer to any type-specific data attached to this actor. See also br_model br_material br_camera br_light 3.1.1.2 Actor types Description Available actor types. Definitions BR_ACTOR_NONE A dummy actor, used to assist the layout and organisation of a hierarchy. BR_ACTOR_MODEL An object in a scene. The actor references a model structure and default material. BR_ACTOR_LIGHT A light source . The actor references type, positional, directional and colour information in a br_light structure, through the type_data pointer. BR_ACTOR_CAMERA A point from which a scene can be rendered from. The actor references positional, direction and field- of-view information in a br_camera structure, through the type_data pointer. BR_ACTOR_BOUNDS A bounding box . The actor references a br_bounds structure through the type_data pointer, giving the dimensions of the cuboid which contains all or most of this actors descendants. If the bounding box is off-screen, none of its descendants is rendered. BR_ACTOR_BOUNDS_CORRECT A guaranteed bounding box, containing all this actor's descendants. If the bounding box is on-screen, no on-screen check is performed when its descendants are rendered. BR_ACTOR_CLIP_PLANE A clipping plane. The actor references a br_vector4 through the type_data pointer, giving the coefficients of the plane equation of the clip plane. See also br_actor br_light br_camera br_model br_bounds 3.1.1.3 Rendering style Description Available rendering styles. When BR_RSTYLE_DEFAULT is used, the rendering style is inherited from the most distant ancestor in the world hierarchy with a non-default style. Definitions BR_RSTYLE_DEFAULT Default style. BR_RSTYLE_NONE Do not render this actor. BR_RSTYLE_POINTS Render vertices only. BR_RSTYLE_EDGES Render edges only with lines. BR_RSTYLE_FACES Render faces. BR_RSTYLE_BOUNDING_POINTS Render bounding box corners with points. BR_RSTYLE_BOUNDING_EDGES Render bounding box edges with lines. BR_RSTYLE_BOUNDING_FACES Render bounding box faces. See also br_actor 3.1.2 Functions 3.1.2.1 Actor functions summary Syntax br_actor * BrActorAllocate(br_uint_8 actor_type, void *type_data); void BrActorFree(br_actor *a); br_actor * BrActorLoad(char *filename); br_uint_32 BrActorLoadMany(char *filename, br_actor **actors, br_uint_16 num); br_uint_32 BrActorSave(char *filename, br_actor *actor); br_uint_32 BrActorSaveMany(char *filename, br_actor **actors, br_uint_16 num); br_actor * BrActorAdd(br_actor *parent, br_actor *a); br_actor * BrActorRemove(br_actor *a); br_actor * BrActorSearch(br_actor *root, char *pattern); br_uint_32 BrActorSearchMany(br_actor *root, char *pattern, br_actor **actors, int max); br_uint_32 BrActorEnum(br_actor *parent, br_actor_enum_cbfn *callback, void *arg); void BrActorRelink(br_actor *parent, br_actor *a); br_uint_8 BrActorToActorMatrix34(br_matrix34 *m, br_actor *a, br_actor *b); void BrActorToScreenMatrix4(br_matrix4 *m, br_actor *a, br_actor *camera); Although many of these functions are similar to those in 'The Registry', they are documented here separately as they relate to hierarchies, rather than individual items. 3.1.2.2 BrActorAllocate Syntax br_actor * BrActorAllocate(br_uint_8 actor_type, void *type_data); Description Allocate a new actor. Arguments actor_type Actor type (see section 3.1.1.2). type_date A pointer to type-specific data. If required but given as NULL, suitable defaults are allocated. Return value Returns a pointer to the new actor. 3.1.2.3 BrActorFree Syntax void BrActorFree(br_actor *a); Description Free an actor, and any children it possesses. Arguments a A pointer to the actor to be freed. 3.1.2.4 BrActorLoad Syntax br_actor * BrActorLoad(char *filename); Description Load a hierarchy of actors. Arguments *filename Name of the file containing the hierarchy. Return value Returns a pointer to the actor at the root of the loaded hierarchy, or NULL if unsuccessful. 3.1.2.5 BrActorLoadMany Syntax br_uint_32 BrActorLoadMany(char *filename, br_actor **actors, br_uint_16 num); Description Load a number of actor hierarchies. Arguments *filename Name of the file containing the hierarchies. actors A pointer to an array of pointers to actors. num Maximum number of hierarchies to load. Return value Returns the number of hierarchies loaded successfully. The pointer array is filled with pointers to the loaded actors. 3.1.2.6 BrActorSave Syntax br_uint_32 BrActorSave(char *filename, br_actor *actor); Description Save a hierarchy of actors. Arguments *filename Name of the file to save the hierarchy to. actor A pointer to an actor, the root of the hierarchy. Return value Returns NULL if the hierarchy could not be saved. 3.1.2.7 BrActorSaveMany Syntax br_uint_32 BrActorSaveMany(char *filename, br_actor **actors, br_uint_16 num); Description Save a number of actor hierarchies. Arguments *filename Name of the file to save the hierarchies to. actors A pointer to an array of pointers to actors. num Number of hierarchies to save. Return value Returns the number of hierarchies saved successfully. 3.1.2.8 BrActorAdd Syntax br_actor * BrActorAdd(br_actor *parent, br_actor *a); Description Add an actor hierarchy as a child of a given parent. Arguments parent A pointer to the parental actor. a A pointer to its new child. Return value Returns a pointer to the added hierarchy. 3.1.2.9 BrActorRemove Syntax br_actor * BrActorRemove(br_actor *a); Description Remove an actor hierarchy from its parent. Arguments a A pointer to the hierarchy to remove. Return value Returns a pointer to the removed hierarchy. 3.1.2.10 BrActorSearch Syntax br_actor * BrActorSearch(br_actor *root, char *pattern); Description Find the first named actor matching a pattern in a given hierarchy. The search pattern can include the standard wildcards '*' and '?'. The search is anchored to the root of the given hierarchy and the search sub-strings for each level in it are delimited with the '/' character. Arguments root A pointer to an actor hierarchy. *pattern Search pattern. Return value Returns a pointer to an actor if found, otherwise NULL. Example br_actor *actor; ... BrActorSearch(actor,"*/*/example_actor"); 3.1.2.11 BrActorSearchMany Syntax br_uint_32 BrActorSearchMany(br_actor *root, char *pattern, br_actor **actors, int max); Description Search for a number of named actors in a given hierarchy. The search pattern is given as for BrActorSearch. Arguments root A pointer to an actor hierarchy. *pattern Search pattern. actors A pointer to an array of pointers to actors. max Maximum number of actors to find. Return value Returns the number of actors found. The pointer array is filled with pointers to the found actors. 3.1.2.12 BrActorEnum Syntax br_uint_32 BrActorEnum(br_actor *parent, br_actor_enum_cbfn *callback, void *arg); Description Invoke a callback function for each one of an actors children. The callback is passed a pointer to each child actor, and its second argument is an optional pointer supplied by the user. The callback itself returns a br_uint_32 value. The enumeration will halt at any stage if the return value is non-zero. As demonstrated in the example, the BR_CALLBACK macro must be used to ensure compiler compatibility. Arguments parent A pointer to an actor. callback A pointer to a callback function. arg An optional argument to pass to the callback function. Return value Returns the first non-zero callback return value, or zero if all children are enumerated. Example br_uint_32 BR_CALLBACK example_callback(br_actor *actor, void *arg) { br_uint_32 value; return(value); } ... { br_actor *example_actor; ... BrActorEnum(example_actor, &example_callback, NULL); /* Invoke callback for all children of this actor */ } 3.1.2.13 BrActorRelink Syntax void BrActorRelink(br_actor *parent, br_actor *a); Description Move an actor in a hierarchy, but preserve its apparent world transformation by manipulating its own transformation as necessary. Arguments a A pointer to an actor. parent A pointer to its new parent. 3.1.2.14 BrActorToActorMatrix34 Syntax br_uint_8 BrActorToActorMatrix34(br_matrix34 *m, br_actor *a, br_actor *b); Description Accumulate the transformations between one actor and another, representing the result as a matrix. Arguments m A pointer to the destination matrix. a,b Pointers to the actors to accumulate between. Return value Returns the type of the accumulated transformation (see section 3.11.1.2). 3.1.2.15 BrActorToScreenMatrix4 Syntax void BrActorToScreenMatrix4(br_matrix4 *m, br_actor *a, br_actor *camera); Description Accumulate the transformations between an actor and the screen, representing the result as a matrix. Arguments m A pointer to the destination matrix. a A pointer to an actor. camera A pointer to a camera actor. ΓòÉΓòÉΓòÉ 4.2. 3.2 Lights ΓòÉΓòÉΓòÉ 3.2.1 Datatypes 3.2.1.1 br_light Structure typedef struct br_light { char *identifier; br_uint_8 type; br_colour colour; br_scalar attenuation_c; br_scalar attenuation_l; br_scalar attenuation_q; br_angle cone_outer; br_angle cone_inner; } br_light; Description BRender's light data structure. Members *identifier Light name. type Light type (see section 3.2.1.2). colour Light colour (when rendering in true colour). attenuation_c Light intensity. attenuation_l Linear attenuation factor for point and spot lights. attenuation_q Quadratic attenuation factor for point and spot lights. cone_inner The angle giving the cone of full-intensity light cast by a spot light. cone_outer The angle giving the cone of illumination of a spot light. The linear and quadratic attenuation factors determine the degree by which light intensity falls off with respect to distance and squared distance from the light source. If d is distance and c, l and q are the constant, linear and quadratic attenuation factors, then light intensity is proportional to 1/(c+d.l+d.d.q). The default values supplied for c, l and q are 1.0, 0.0 and 0.0 respectively. Furthermore, with spot lights, the intensity falls off linearly from maximum to zero in-between the inner and outer cones. See also BrLightEnable BrLightDisable 3.2.1.2 Light types Description Available light types and options. Definitions BR_LIGHT_POINT A point light source, radiating in all directions. BR_LIGHT_DIRECT A directed light source. The light is infinitely distant and shines along the Z- axis of the light actor. BR_LIGHT_SPOT A spot light, with both spatial location and direction. A spot light has a cone of illumination and shines along the Z- axis of the light actor. BR_LIGHT_TYPE A mask which can be used to strip off any non-type information, for instance, option flags. BR_LIGHT_VIEW An option flag. When set, lighting calculations are performed in view space rather than model space. This is slower, but prevents odd anomalies if non-uniform scalings are used on models. See also br_light BrMatrix4Perspective 3.2.2 Functions 3.2.2.1 BrLightEnable Syntax void BrLightEnable(br_actor *l); Description Enable a light source. By default, light sources are disabled. Arguments l A pointer to a light actor. See also BrLightDisable 3.2.2.2 BrLightDisable Syntax void BrLightDisable(br_actor *l); Description Disable a light source. Arguments l A pointer to a light actor. See also BrLightEnable ΓòÉΓòÉΓòÉ 4.3. 3.3 Cameras ΓòÉΓòÉΓòÉ 3.3.1 Datatypes 3.3.1.1 br_camera Structure typedef struct br_camera { char *identifier; br_uint_8 type; br_angle field_of_view; br_scalar hither_z; br_scalar yon_z; br_scalar aspect; br_scalar width; br_scalar height; } br_camera; Description BRender's camera data structure. Members *identifier Camera name. type Camera type (see section 3.3.1.2). field_of_view Field of view (the angle subtended between the sides of the view volume). Applies only to perspective cameras. hither_z Front of view volume, in view coordinates. yon_z Back of view volume, in view coordinates. aspect Aspect ratio (the ratio between the sides of the view volume). width, height Width and height of projection surface. Applies only to parallel cameras. See also BrMatrix4Perspective 3.3.1.2 Camera types Description Available camera types. Definitions BR_CAMERA_PARALLEL A parallel camera. Object size is independant of its distance from the camera. BR_CAMERA_PERSPECTIVE A standard perspective camera. See also br_camera ΓòÉΓòÉΓòÉ 4.4. 3.4 Clipping Planes ΓòÉΓòÉΓòÉ 3.4.1 Functions 3.4.1.1 BrClipPlaneEnable Syntax void BrClipPlaneEnable(br_actor *cp); Description Enable a clip plane. By default, clip planes are disabled. Arguments cp A pointer to a clip plane actor. 3.4.1.2 BrClipPlaneDisable Syntax void BrClipPlaneDisable(br_actor *cp); Description Disable a clip plane. Arguments cp A pointer to a clip plane actor. ΓòÉΓòÉΓòÉ 4.5. 3.5 Models ΓòÉΓòÉΓòÉ 3.5.1 Datatypes 3.5.1.1 br_model Structure typedef struct br_model { char *identifier; br_vertex *vertices; br_face *faces; br_uint_16 nvertices; br_uint_16 nfaces; br_vector3 pivot; br_uint_16 flags; br_model_custom_cbfn *custom; void *user; br_scalar radius; br_bounds bounds; } br_model; Description Brender's model data structure, describing a mesh of triangles. Members *identifier Model name. vertices A pointer to an array of vertices. faces A pointer to an array of faces. nvertices Number of vertices in the model. nfaces Number of faces in the model. pivot A vector giving the model's pivot point, or centre of rotation, relative to its origin. This is the point at which it 'attaches' to its parent. flags Model flags (see section 3.5.1.2). custom A custom model callback function. user An optional user-supplied pointer. radius The bounding radius of the model. bounds An axis-aligned bounding box of the model, given in the model's own coordinate system. See also BrModelLoad BrModelUpdate 3.5.1.2 Model flags Description Available model flags. Definitions BR_MODF_DONT_WELD Vertices with the same coordinates cannot be merged. BR_MODF_KEEP_ORIGINAL Don't free original vertices and faces during model update. BR_MODF_GENERATE_TAGS Allocate and fill face and vertex tag tables, which map updated face and vertex indices back to the original face and vertex indices. BR_MODF_QUICK_UPDATE Perform fast model update. This may produce slower models. BR_MODF_CUSTOM Invoke a custom callback for this model (see section 3.5.3). See also BrModelUpdate 3.5.1.3 br_face Structure struct br_face { br_uint_16 vertices[3]; br_material *material; br_uint_16 smoothing; br_uint_8 flags; } br_face; Description The face data structure, describing a single triangular face. Members vertices An array of vertex indices specifying the vertices of this face. material Pointer to the material structure associated with this face. smoothing A 16-bit field in which each bit represents a smoothing group. If, when smooth-shading a surface, two adjacent faces share a smoothing group, the edge between them will be smooth. flags Face flags (see section 3.5.1.4). See also br_material br_model br_vertex 3.5.1.4 Face flags Description Face flags, indicating whether the edges of the face abut co-planar faces, and thus do not need to be drawn in the wire-frame render style BR_RSTYLE_EDGES. Definitions BR_FACEF_COPLANAR_0 The face adjoining edge 0 is coplanar with this face. BR_FACEF_COPLANAR_1 The face adjoining edge 1 is coplanar with this face. BR_FACEF_COPLANAR_2 The face adjoining edge 2 is coplanar with this face. 3.5.1.5 br_vertex Structure typedef struct br_vertex { br_vector3 p; br_vector2 map; br_uint_8 index; br_uint_8 red; br_uint_8 grn; br_uint_8 blu; } br_vertex; Description The vertex data structure, describing a single vertex in a model. Members p Coordinates of a point in model space. map Texture coordinates of this vertex. index Colour index for pre-lit models. red, grn, blu True colour values for pre-lit models. See also br_face br_model 3.5.1.6 br_bounds Structure typedef struct br_bounds { br_vector3 min; br_vector3 max; } br_bounds; Description A data structure describing an axis-aligned bounding box for a model or hierarchy of actors. Members min Co-ordinates of the minimal corner of the bounding box. max Co-ordinates of the maximal corner of the bounding box. 3.5.2 Functions 3.5.2.1 Model functions summary br_model * BrModelAllocate(char *name, int nvertices, int nfaces); void BrModelFree(br_model *model); br_model * BrModelLoad(char *filename); br_uint_32 BrModelLoadMany(char *filename,br_model **models,int num); br_uint_32 BrModelSave(char *filename,br_model *model); br_uint_32 BrModelSaveMany(char *filename,br_model **models,int num); br_model * BrModelAdd(br_model *model); br_uint_32 BrModelAddMany(br_model **models, int n); br_model * BrModelRemove(br_model *model); br_uint_32 BrModelRemoveMany(br_model **items, int n); br_model * BrModelFind(char *pattern); br_uint_32 BrModelFindMany(char *pattern, br_model **models, int max); br_model_find_cbfn * BrModelFindHook(br_model_find_cbfn *hook); br_uint_32 BrModelCount(char *pattern); br_uint_32 BrModelEnum(char *pattern); void BrModelUpdate(br_model *model, br_uint_16 flags); void BrModelApplyMap(br_model *model,int map_type, br_matrix34 *xform); br_matrix34 * BrModelFitMap(br_model *model, int axis_0, int axis_1, br_matrix34 *transform); Most of these functions are standard BRender Registry functions and are documented under 'The Registry'. Only those exclusive to models are documented here. 3.5.2.2 BrModelApplyMap Syntax void BrModelApplyMap(br_model *model, int map_type, br_matrix34 *xform); Description Generate texture coordinates (u,v) for a model's vertices, using a planar, spherical, cylindrical, disc or null mapping. The model's vertices can be pre-transformed by an optional matrix. Arguments model A pointer to a model. map_type Mapping type (see section 3.5.2.3). xform A pointer to an optional matrix. If NULL, the identity transformation is used. See also BrModelFitMap 3.5.2.3 Mapping types Description Available texture-mapping schemes. Definitions BR_APPLYMAP_NONE No mapping. u = 0 v = 0 BR_APPLYMAP_PLANE A planar mapping. BR_APPLYMAP_CYLINDER A cylindrical mapping. This can be visualised by imagining a texture wrapped around the outside of a cylinder. BR_APPLYMAP_SPHERE A spherical mapping. Similar to a cylindrical mapping, but the ends of the cylinder are shrunk to single points. BR_APPLYMAP_DISC A disc mapping. This can be visualised by considering a cylindrical mapping, shrinking one end of the cylinder to a point and then flattening it to form a disc. 3.5.2.4 BrModelFitMap Syntax br_matrix34 * BrModelFitMap(br_model *model, int axis_0, int axis_1, br_matrix34 *transform); Description Generate a transformation which will map the bounds of a model onto a cube defined by the corner coordinates (-1,-1,-1) and (1,1,1). When passed to BrModelApplyMap, texture coordinates will be generated which fit the model exactly. The two axes along which the mapping is applied must be specified. Arguments model A pointer to a model. transform A pointer to the destination transformation matrix. axis_0, axis_1 Mapping axes, defined as follows: BR_FITMAP_PLUS_X BR_FITMAP_PLUS_Y BR_FITMAP_PLUS_Z BR_FITMAP_MINUS_X BR_FITMAP_MINUS_Y BR_FITMAP_MINUS_Z Return value Returns a pointer to the destination transformation matrix. See also BrModelApplyMap 3.5.3 Custom model callback functions 3.5.3.1 Callback function type Syntax typedef void BR_CALLBACK br_model_custom_cbfn(br_actor *actor, br_model *model, br_material *material, br_uint_8 style, int on_screen, br_matrix34 *model_to_view, br_matrix4 *model_to_screen); Description Type definition for a custom model callback function. The BR_CALLBACK macro must be used to ensure compiler compatibility. The functions given in sections 3.5.3.2 to 3.5.3.8 are used within custom model callbacks. They relate to the model which invoked the callback. The following arguments are passed to the callback. Arguments actor A pointer to the model's actor structure. model A pointer to the model itself. material A pointer to the model's default material. style The model's rendering style. on_screen On-screen flag (either OSC_PARTIAL or OSC_ACCEPT). model_to_view A pointer to a matrix giving the model to view space transformation. model_to_screen A pointer to a matrix giving the model to screen transformation. 3.5.3.2 BrOnScreenCheck Syntax br_uint_8 BrOnScreenCheck(br_bounds *bounds); Description Check the model's bounding box against the view volume. Arguments bounds A pointer to a br_bounds structure giving the model's bounding box dimensions. Return value Returns one of the following: OSC_REJECT Completely off-screen. OSC_PARTIAL Partially on-screen. OSC_ACCEPT Completely on-screen. 3.5.3.3 BrOriginToScreenXY Syntax br_uint_8 BrOriginToScreenXY(br_vector2 *screen); Description Transform and project the model's origin onto the screen. Arguments screen A pointer to the destination vector. Return value Returns NULL if the origin is in front of the camera. 3.5.3.4 BrOriginToScreenXYZO Syntax br_uint_32 BrOriginToScreenXYZO(br_vector3 *screen); Description Transform and project the model's origin onto the screen, generating X, Y and Z coordinates. If the point is off-screen, it is not projected. Arguments screen A pointer to the destination vector. Return value Returns the origin's outcode, made up from the following flags: OUTCODE_LEFT = 0x01 Set if outside left plane. OUTCODE_RIGHT = 0x02 Set if outside right plane. OUTCODE_TOP = 0x04 Set if outside top plane. OUTCODE_BOTTOM = 0x08 Set if outside bottom plane. OUTCODE_HITHER = 0x10 Set if outside hither plane. OUTCODE_YON = 0x20 Set if outside yon plane. 3.5.3.5 BrPointToScreenXY Syntax br_uint_8 BrPointToScreenXY(br_vector2 *screen, br_vector3 *point); Description Transform and project a single point in the model's coordinate system onto the screen. Arguments screen A pointer to the destination vector. point A pointer to the source vector. Return value Returns NULL if the point is in front of the camera. 3.5.3.6 BrPointToScreenXYMany Syntax void BrPointToScreenXYMany(br_vector2 *screens, br_vector3 *points, br_uint_32 npoints); Description Transform and project a number of points in the model's coordinate system onto the screen. Arguments screens A pointer to an array of destination vectors. points A pointer to an array of source vectors. npoints Number of points. 3.5.3.7 BrPointToScreenXYZO Syntax br_uint_32 BrPointToScreenXYZO(br_vector3 *screen, br_vector3 *point); Description Transform and project a single point in the model's coordinate system onto the screen, generating X, Y and Z coordinates. If the point is off-screen, it is not projected. Arguments screen A pointer to the destination vector. point A pointer to the source vector. Return value Returns the point's outcode. See also BrOriginToScreenXYZO 3.5.3.8 BrPointToScreenXYZOMany Syntax void BrPointToScreenXYZOMany(br_vector3 *screens, br_uint_32 *outcodes, br_vector3 *points, br_uint_32 npoints); Description Transform and project a number of points in the model's coordinate system onto the screen, generating outcodes and X, Y and Z coordinates. If any points are off-screen, they are not projected. Arguments screens A pointer to an array of destination vectors. outcodes A pointer to an array of outcodes. points A pointer to an array of source vectors. npoints Number of points. See also BrOriginToScreenXYZO ΓòÉΓòÉΓòÉ 4.6. 3.6 Materials ΓòÉΓòÉΓòÉ 3.6.1 Datatypes 3.6.1.1 br_material Structure typedef struct br_matrix23 { br_scalar m[3][2]; } br_matrix23; typedef struct br_material { char *identifier; br_colour colour; br_ufraction ka; br_ufraction kd; br_ufraction ks; br_scalar power; br_uint_32 flags; br_matrix23 map_transform; br_uint_8 index_base; br_uint_8 index_range; br_pixelmap *colour_map; br_pixelmap *index_shade; } br_material; Description A structure which describes the appearance of a material that can be applied to a surface. Members *identifier Material name. colour Material colour, when rendering in true colour. ka The ambient lighting contribution for this material. kd The directional lighting contribution for this material. Zero will give a matte surface, whereas one will give a very smooth surface. ks The specular lighting contribution for this material. Zero will give a matte surface, whereas one will give a glossy, polished surface with highlights. power Specular power, determining the 'spread' of a specular highlight. Zero will give a diffuse highlight, whereas 100 will give a very localised highlight. flags Flags determining how this material is rendered (see section 3.6.1.2). map_transform A matrix representing a general texture map transformation, allowing textures to be rotated, scaled, sheared or translated as necessary. index_base The base of an index into a shade table. Used for flat or smooth shaded materials. index_range The range of an index into a shade table. colour_map A pointer to a pixelmap containing the texture for this material. If NULL, the material is not texture-mapped. Zero elements in the texture will appear transparent. index_shade A pointer to a shade table for this material. See also br_colour br_pixelmap BrEnvironmentSet BrModelApplyMap BrModelFitMap 3.6.1.2 Material flags Description Available material rendering styles. Definitions BR_MATF_LIGHT The material is lit. BR_MATF_PRELIT The material is pre-lit, in which case colours are taken directly from the model's vertex structures. BR_MATF_SMOOTH The material is smooth (Gouraud) shaded. BR_MATF_ENVIRONMENT_I The material is environment-mapped with a viewpoint at infinity. BR_MATF_ENVIRONMENT_L The material is environment-mapped with a local viewpoint. BR_MATF_PERSPECTIVE The material is perspective texture-mapped. BR_MATF_DECAL Zero elements in the texture map are transparent, but allow the non-texture mapped material underneath to show through. For example, this could be used to add symbols or logos to a smooth shaded model. BR_MATF_ALWAYS_VISIBLE The material will always be visible, and so back-face culling need not be performed. BR_MATF_TWO_SIDED The material has two sides, and lighting calculations are performed for both of them. BR_MATF_FORCE_Z_0 The material is automatically in front of all other materials. 3.6.2 Functions 3.6.2.1 Material functions summary br_material * BrMaterialAllocate(char *name); void BrMaterialFree(br_material *material); br_material * BrMaterialLoad(char *filename); br_uint_32 BrMaterialLoadMany(char *filename, br_material **materials, br_uint_16 num); br_uint_32 BrMaterialSave(char *filename, br_material *material); br_uint_32 BrMaterialSaveMany(char *filename, br_material **materials, br_uint_16 num); br_material * BrMaterialAdd(br_material *material); br_uint_32 BrMaterialAddMany(br_material **items, int n); br_material * BrMaterialRemove(br_material *material); br_uint_32 BrMaterialRemoveMany(br_material **items, int n); br_material * BrMaterialFind(char *pattern); br_uint_32 BrMaterialFindMany(char *pattern, br_material **materials, int max); br_material_find_cbfn * BrMaterialFindHook(br_material_find_cbfn *hook); br_uint_32 BrMaterialCount(char *pattern); br_uint_32 BrMaterialEnum(char *pattern); void BrMaterialUpdate (br_material *material, br_uint_16 flags); These functions are documented under 'The Registry'. ΓòÉΓòÉΓòÉ 4.7. 3.7 Maps ΓòÉΓòÉΓòÉ 3.7.1 Functions 3.7.1.1 Map functions summary br_pixelmap * BrMapAdd(br_pixelmap *pixelmap); br_uint_32 BrMapAddMany(br_pixelmap **pixelmaps, int n); br_pixelmap * BrMapRemove(br_pixelmap *pixelmap); br_uint_32 BrMapRemoveMany(br_pixelmap **pixelmaps, int n); br_pixelmap * BrMapFind(char *pattern); br_uint_32 BrMapFindMany(char *pattern, br_pixelmap **pixelmaps, int max); br_map_find_cbfn * BrMapFindHook(br_map_find_cbfn *hook); br_uint_32 BrMapCount(char *pattern); br_uint_32 BrMapEnum(char *pattern); void BrMapUpdate(br_pixelmap *pixelmap, br_uint_16 flags); br_actor * BrEnvironmentSet(br_actor *a); Most of these functions are standard BRender Registry functions and are documented under 'The Registry'. Only those exclusive to maps are documented here. 3.7.1.2 BrEnvironmentSet Syntax br_actor * BrEnvironmentSet(br_actor *a); Description Set a new environment anchor. By default, the reflective effect produced by an environment map on the surface of a model appears to rotate with the model itself. If this is unsatisfactory, the map can be anchored to an actor. If the actor is the root of a world hierarchy, then reflections will appear more realistic. Arguments a A pointer to an actor. Return value Returns a pointer to the old environment anchor. ΓòÉΓòÉΓòÉ 4.8. 3.8 Pixelmaps ΓòÉΓòÉΓòÉ 3.8.1 Datatypes 3.8.1.1 br_pixelmap Structure typedef struct br_pixelmap { char *identifier; void *pixels; br_pixelmap *map; br_int_16 row_bytes; br_uint_8 type; br_uint_8 flags; br_uint_16 base_x; br_uint_16 base_y; br_uint_16 width; br_uint_16 height; br_int_16 origin_x; br_int_16 origin_y; void *device; } br_pixelmap; Description BRender's pixelmap structure, used for texture maps, tables, colour buffers and Z-buffers. Members *identifier An optional name for texture maps and tables. pixels A pointer to raw pixel data. map A pointer to a colour-map, used when pixels colours are indexed. row_bytes The number of bytes between pixels at the same column of adjacent rows. type Individual pixel type (see section 3.8.1.2). base_x,base_y Coordinates of the top-left of the region in use, relative to the pixel pointed to by pixels. width,height Width and height of pixelmap, in pixels. origin_x,origin_y Local origin for rendering into the pixelmap, relative to base_x,base_y. device A device pointer, used if the pixelmap originated from a device. 3.8.1.2 Pixelmap types Description Various types of pixel. Definitions Unless stated otherwise, the numerical suffixes give the number of bits used per colour or alpha channel, per pixel. BR_PMT_INDEX_1 Each pixel is an index into a colour map. The BR_PMT_INDEX_2 numerical suffix gives the number of bits used BR_PMT_INDEX_4 per pixel. BR_PMT_INDEX_8 BR_PMT_RGB_555 True colour RGB, 16 bits total per pixel. BR_PMT_RGB_565 True colour RGB, 16 bits total per pixel. BR_PMT_RGB_888 True colour RGB, 24 bits total per pixel. BR_PMT_RGBX_888 True colour RGB, 32 bits total per pixel. BR_PMT_RGBA_8888 True colour RGB with an alpha channel, 32 bits total per pixel. BR_PMT_DEPTH_16 The pixelmap is used as a Z-buffer. The numerical BR_PMT_DEPTH_32 suffix gives the number of bits used per pixel. 3.8.2 Functions 3.8.2.1 Pixelmap functions summary br_pixelmap * BrPixelmapAllocate(br_uint_8 type, br_uint_16 w, br_uint_16 h, void *pixels, int flags); br_pixelmap * BrPixelmapAllocateSub(br_pixelmap *pm, br_uint_16 x, br_uint_16 y, br_uint_16 w, br_uint_16 h); void BrPixelmapFree(br_pixelmap *pm); br_pixelmap * BrPixelmapLoad(char *filename); br_uint_32 BrPixelmapLoadMany(char *filename, br_pixelmap **pixelmaps, br_uint_16 num); br_uint_32 BrPixelmapSave(char *filename, br_pixelmap *pixelmap); br_uint_32 BrPixelmapSaveMany(char *filename, br_pixelmap **pixelmaps, br_uint_16 num); br_uint_16 BrPixelmapPixelSize(br_pixelmap *pm); br_uint_16 BrPixelmapChannels(br_pixelmap *pm); br_pixelmap * BrPixelmapDoubleBuffer(br_pixelmap *dst, br_pixelmap *src); br_pixelmap * BrPixelmapMatch(br_pixelmap *src, int match_type); br_pixelmap * BrPixelmapClone(br_pixelmap *src); void BrPixelmapFill(br_pixelmap *dat, br_uint_32 colour); void BrPixelmapCopy(br_pixelmap *dst, br_pixelmap *src); void BrPixelmapDirtyRectangleCopy(br_pixelmap *dst, br_pixelmap *src, br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h); void BrPixelmapDirtyRectangleFill(br_pixelmap *dst, br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h, br_uint_32 colour); void BrPixelmapRectangleCopy (br_pixelmap *dst, br_int_16 dx, br_int_16 dy, br_pixelmap *src, br_int_16 sx, br_int_16 sy, br_uint_16 w, br_uint_16 h); void BrPixelmapRectangleFill(br_pixelmap *dst, br_int _16 x, br_int_32 y, br_uint_16 w, br_uint_16 h, br_uint_32 colour); void BrPixelmapPlot(br_pixelmap *dst, br_int_16 x, br_int_16 y, br_uint_32 colour); 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); void BrPixelmapText(br_pixelmap *dst, br_int_16 x, br_int_16 y, br_uint_32 colour, br_font *font, char *text); void BrPixelmapTextF(br_pixelmap *dst,br_int_16 x, br_int_16 y, br_uint_32 colour, br_font *font, char *fmt, ...); br_uint_16 BrPixelmapTextWidth(br_pixelmap *dst, br_font *font, char *text); br_uint_16 BrPixelmapTextHeight(br_pixelmap *dst, br_font *font); Some of these functions are standard BRender Registry functions and are documented under 'The Registry'. Only those exclusive to pixelmaps are documented here. 3.8.2.2 BrPixelmapPixelSize Syntax br_uint_16 BrPixelmapPixelSize(br_pixelmap *pm); Description Find the pixel size for a given pixelmap. Arguments pm A pointer to a pixelmap. Return value Returns the size of each pixel, in bits. 3.8.2.3 BrPixelmapChannels Syntax br_uint_16 BrPixelmapChannels(br_pixelmap *pm); Description Find the channels available for a given pixelmap. Arguments pm A pointer to a pixelmap. Return value Returns a mask giving the available channels, given the following definitions: BR_PMCHAN_INDEX = 0x0001 BR_PMCHAN_RGB = 0x0002 BR_PMCHAN_DEPTH = 0x0004 BR_PMCHAN_ALPHA = 0x0008 BR_PMCHAN_YUV = 0x0010 3.8.2.4 BrPixelmapDoubleBuffer Syntax br_pixelmap * BrPixelmapDoubleBuffer(br_pixelmap *dst, br_pixelmap *src); Description If the destination pixelmap relates to a device, for example a graphics hardware screen, then the source 'off-screen' pixelmap is swapped with the destination pixelmap. Otherwise, the source pixelmap is copied to the destination pixelmap. Arguments dst A pointer to the destination pixelmap. src A pointer to the source pixelmap. Return value Always returns a pointer to an 'off-screen' pixelmap which the next frame can be rendered into. 3.8.2.5 BrPixelmapMatch Syntax br_pixelmap * BrPixelmapMatch(br_pixelmap *src, int match_type); Description Given a pixelmap, allocate either a depth buffer or an off-screen colour buffer with the same dimensions. Arguments src A pointer to the source pixelmap. match_type Either BR_PMMATCH_OFFSCREEN or BR_PMMATCH_DEPTH_16. Return value Returns a pointer to the matching pixelmap. 3.8.2.6 BrPixelmapClone Syntax br_pixelmap * BrPixelmapClone(br_pixelmap *src); Description Clone a pixelmap. Duplicate copies of raw pixel and colour-map data are made. Arguments src A pointer to the source pixelmap. Return value Returns a pointer to the new pixelmap. Example br_pixelmap *image, *working_copy; ... image = BrPixelmapLoad("backdrop.pix"); working_copy = BrPixelmapClone(image); 3.8.2.7 BrPixelmapFill Syntax void BrPixelmapFill(br_pixelmap *dat, br_uint_32 colour); Description Fill a pixelmap with a given value. Arguments dat A pointer to the pixelmap to be filled. colour Value to set each pixel to. 3.8.2.8 BrPixelmapCopy Syntax void BrPixelmapCopy(br_pixelmap *dst, br_pixelmap *src); Description Copy the data in one pixelmap to another. The source and destination pixelmaps must have the same type and dimensions. Arguments dst A pointer to the destination pixelmap. src A pointer to the source pixelmap. Example ... BrPixelmapCopy(offscreen, backdrop); 3.8.2.9 BrPixelmapDirtyRectangleCopy Syntax void BrPixelmapDirtyRectangleCopy(br_pixelmap *dst, br_pixelmap *src, br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h) Description Copy a rectangular window of data from one pixelmap to the same position in another pixelmap. The source and destination pixelmaps must have the same type and dimensions. This function can be used in conjunction with a rendering callback to copy only those regions of a pixelmap that have actually been rendered to. Arguments dst A pointer to the destination pixelmap. src A pointer to the source pixelmap. x,y Coordinates of the rectangle's top left corner. w,h Rectangle width and height (in pixels). The width is automatically rounded up to the next multiple of four pixels. Example br_int_16 drx, dry; br_uint_16 drw, drh; br_pixelmap *offscreen, *backdrop; ... BrPixelmapDirtyRectangleCopy(offscreen,backdrop,drx,dry,drw,drh); See also br_renderbounds_cbfn BrZbSetRenderBoundsCallback 3.8.2.10 BrPixelmapDirtyRectangleFill Syntax void BrPixelmapDirtyRectangleFill(br_pixelmap *dst, br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h, br_uint_32 colour); Description Set a rectangular window in pixelmap to a given value. This function can be used in conjunction with a rendering callback to set only those regions of a pixelmap that have actually been rendered to. Arguments dst A pointer to the destination pixelmap. x,y Coordinates of the rectangle's top left corner. w,h Rectangle width and height (in pixels). The width is automatically rounded up to the next multiple of four pixels. colour Value to set each pixel to. Example br_uint_32 zfar = 0xffffffff; br_int_16 drx, dry; br_unit_16 drw, drh; br_pixelmap *zbuffer; ... BrPixelmapDirtyRectangleFill(zbuffer,drx,dry,drw,drh,zfar); 3.8.2.11 BrPixelmapRectangleCopy Syntax void BrPixelmapRectangleCopy (br_pixelmap *dst, br_int_16 dx, br_int_16 dy, br_pixelmap *src, br_int_16 sx, br_int_16 sy, br_uint_16 w, br_uint_16 h); Description Copy a rectangular window from one pixelmap to another. Arguments dst A pointer to the destination pixelmap. dx,dy Coordinates of the destination rectangle's top left corner. src A pointer to the source pixelmap. sx,sy Coordinates of the source rectangle's top left corner. w,h Rectangle width and height (in pixels). 3.8.2.12 BrPixelmapRectangleFill Syntax void BrPixelmapRectangleFill(br_pixelmap *dst, br_int _16 x, br_int_16 y, br_unint_16 w, br_uint_16 h, br_uint_32 colour); Description Fill a rectangular window in a pixelmap with a given value. Arguments dst A pointer to the destination pixelmap. x,y Coordinates of the rectangle's top left corner. w,h Rectangle width and height (in pixels). colour Value to set each pixel to. Example br_int_16 x,y; br_unit_16 w,h; br_pixelmap *offscreen; ... BrPixelmapRectangleFill(offscreen,x,y,w,h,0); 3.8.2.13 BrPixelmapPlot Syntax void BrPixelmapPlot(br_pixelmap *dst, br_int_16 x, br_int_16 y, br_uint_32 colour); Description Set a pixel to a given value. Arguments dst A pointer to the destination pixelmap. x,y Pixel coordinates. colour Pixel value. 3.8.2.14 BrPixelmapLine Syntax 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); Description Draw a line in a pixelmap between (x1,y1) and (x2,y2), clipping it to the edges of the pixelmap if necessary. Arguments dst A pointer to the destination pixelmap. x1,y1,x2,y2 Coordinates of the line's endpoints. colour Value to set each pixel in the line to. 3.8.2.15 BrPixelmapText# Syntax void BrPixelmapText(br_pixelmap *dst, br_int_16 x, br_int_16 y, br_uint_32 colour, br_font *font, char *text); void BrPixelmapTextF(br_pixelmap *dst,br_int_16 x, br_int_16 y, br_uint_32 colour, br_font *font, char *fmt, ...); Description Write a string into a pixelmap in a given font. BrPixelmapTextF will accept format strings and arguments as for the standard printf function. Arguments dst A pointer to the destination pixelmap. x,y Coordinates of text's top left corner. colour Value to set each text pixel to. *text A string. *fmt A format string (as for printf). font A pointer to a BRender font, or NULL for the default font. The following pointers are available: BrFontFixed3x5 BrFontProp4x6 BrFontProp7x9 Example br_uint_32 colour; br_pixelmap *pmap; ... BrPixelmapText(pmap,0,0,colour,BrFontProp7x9,"Example text..."); 3.8.2.16 BrPixelmapTextWidth Syntax br_uint_16 BrPixelmapTextWidth(br_pixelmap *dst, br_font *font, char *text); Description Find the width of a string for a given font and pixelmap. Arguments dst A pointer to a pixelmap. font A pointer to a BRender font, or NULL for the default font. *text A string. Return value Returns the string width in pixels. If the third argument is NULL, the width of one character is returned. See also BrPixelmapText 3.8.2.17 BrPixelmapTextHeight Syntax br_uint_16 BrPixelmapTextHeight(br_pixelmap *dst, br_font *font); Description Find the height of a font for a given pixelmap. Arguments dst A pointer to a pixelmap. font A pointer to a BRender font, or NULL for the default font. *text A string. Return value Returns the font height in pixels. See also BrPixelmapText ΓòÉΓòÉΓòÉ 4.9. 3.9 Tables ΓòÉΓòÉΓòÉ 3.9.1 Table types 3.9.1.1 Shade tables Description A shade table is a BR_PMT_INDEX_8 pixelmap used when rendering in 256 colour modes. Each entry in the table is an index into a palette. The table can be of arbitrary width and depth, although the default values are 256 and 64, respectively. Each column in the table represents a graduated strip of a single colour, from the darkest possible in the first row, to fully saturated in the last row. Shade tables can be generated by the 'mkshades' tool (see appendix D). 3.9.2 Functions 3.9.2.1 Table functions summary Syntax br_pixelmap * BrTableAdd(br_pixelmap *pixelmap); br_uint_32 BrTableAddMany(br_pixelmap **pixelmaps, int n); br_pixelmap * BrTableRemove(br_pixelmap *pixelmap); br_uint_32 BrTableRemoveMany(br_pixelmap **pixelmaps, int n); br_pixelmap * BrTableFind(char *pattern); br_uint_32 BrTableFindMany(char *pattern, br_pixelmap **pixelmaps, int max); br_table_find_cbfn *BrTableFindHook(br_table_find_cbfn *hook); br_uint_32 BrTableCount(char *pattern); br_uint_32 BrTableEnum(char *pattern); void BrTableUpdate(br_pixelmap *pixelmap, br_uint_16 flags); These functions are documented under 'The Registry'. ΓòÉΓòÉΓòÉ 4.10. 3.10 Colour ΓòÉΓòÉΓòÉ 3.10.1 Datatypes 10.1.1 br_colour Definition typedef unsigned long int br_colour; Description BRender's native colour representation: 32-bit colour. Blue occupies bits 0 to 7, green occupies bits bits 8 to 15, red occupies bits 16 to 23, and an optional alpha value occupies bits 24 to 31. Associated macros BR_COLOUR_RGB(r,g,b) Returns a br_ colour given three 8-bit colour components. BR_COLOUR_RGBA(r,g,b,a) Returns a br_colour given three 8-bit colour components and an 8-bit alpha component. BR_RED(c) Returns the red component of a colour. BR_GRN(c) Returns the green component of a colour. BR_BLU(c) Returns the blue component of a colour. BR_ALPHA(c) Returns the alpha component of a colour. See also br_material br_pixelmap ΓòÉΓòÉΓòÉ 4.11. 3.11 Transforms ΓòÉΓòÉΓòÉ 3.11.1 Datatypes 3.11.1.1 br_transform Structure typedef struct br_transform { br_uint_16 type; union { br_matrix34 mat; struct { br_euler e; br_scalar _pad[7]; br_vector3 t; } euler; struct { br_quat q; br_scalar _pad[5]; br_vector3 t; } quat; struct { br_vector3 look; br_vector3 up; br_scalar _pad[3]; br_vector3 t; } look_up; struct { br_scalar _pad[9]; br_vector3 t; } translate; } t; } br_transform; Description BRender's generic transformation type, used to specify a transformatin from one actor's space to another. Members type Specifies the way in which the transformation is represented. (See section 3.11.1.2) 3.11.1.2 Transform type definitions Description Flags specifying the way in which a generic transformation is represented. Definitions BR_TRANSFORM_MATRIX34 The transform is represented by a 3x4 affine matrix (the most general representation). BR_TRANSFORM_MATRIX34_LP The transform is represented by a 3x4 length-preserving matrix. BR_TRANSFORM_EULER The transform is represented by a set of Euler angles and a translation. BR_TRANSFORM_QUAT The transform is represented by a quaternion and a translation. BR_TRANSFORM_LOOK_UP The transform is represented by a look-at vector, an up vector and a translation. This transform has the effect of making the actor's Z- axis lie along the 'look' vector, and the X+ axis lie along the cross product of the 'look' and 'up' vectors. For example, it is a convenient method of making a camera point toward a particular position. BR_TRANSFORM_TRANSLATION The transform is a translation only. BR_TRANSFORM_IDENTITY The transform is the identity. See also Euler Angles Quaternions Vectors Matrices 3.11.2 Functions 3.11.2.1 Transform functions summary Syntax void BrMatrix34ToTransform(br_transform *xform, br_matrix34 *mat); void BrTransformToMatrix34(br_matrix34 *mat, br_transform *xform); void BrMatrix34PreTransform(br_matrix34 *mat, br_transform *xform); void BrMatrix34PostTransform(br_matrix34 *mat, br_transform *xform); void BrMatrix4PreTransform(br_matrix4 *mat, br_transform *xform); void BrTransformToTransform(br_transform *dest, br_transform *src); The first two groups of functions is documented under 'The Maths Library'. 3.11.2.2 BrTransformToTransform Syntax void BrTransformToTransform(br_transform *dest, br_transform *src); Description Convert from one generic transformation to another. The transformation type in the destination transformation must be set before conversion is performed. In some cases, it may not be possible to preserve all components of a given transformation. For example, when converting from matrix to quaternion, any scaling or shearing components will be lost. Arguments src A pointer to the source transformation. dest A pointer to the destination transformation. ΓòÉΓòÉΓòÉ 5. 4. The Registry ΓòÉΓòÉΓòÉ The Registry is a suite of functions and data structures which simplifies handling items such as materials, models, texture maps, tables and pixelmaps. These functions perform a range of useful and powerful operations on items that have been registered, including the following: Memory allocation and de-allocation Loading and saving items Item preparation and update Enumeration through a callback function Search for items by textual name Counting items In general, all items should be registered before they are used subsequently. There is a similar suite of functions for actors, but they are not documented in this section as they relate to hierarchies, rather than individual items. Similarly, the registry of resource classes is documented under 'The Support Library'. Throughout this chapter, the '#' symbol is used as a wildcard. ΓòÉΓòÉΓòÉ 5.1. 4.1 Registry Functions ΓòÉΓòÉΓòÉ 4.1.1 Allocate/Free 4.1.1.1 BrMaterialAllocate Syntax br_material * BrMaterialAllocate(char *name); Description Allocate a new material. Arguments *name Name of the new material. Return value Returns a pointer to the new material, or NULL if unsuccessful. 4.1.1.2 BrModelAllocate Syntax br_model * BrModelAllocate(char *name, int nvertices, int nfaces); Description Allocate a new model. Arguments *name Name of the new model. nvertices Number of vertices in the new model. nfaces Number of faces in the new model. Return value Returns a pointer to the new model, or NULL if unsuccessful. 4.1.1.3 BrPixelmapAllocate Syntax br_pixelmap * BrPixelmapAllocate(br_uint_8 type, br_uint_16 w, br_uint_16 h, void *pixels, int flags); Description Allocate a new pixelmap. Arguments type Pixelmap type. w Width in pixels. h Height in pixels. pixels A pointer to an existing block of memory. If NULL, the pixel memory is allocated automatically. flags Either BR_PMAF_NORMAL or BR_PMAF_INVERTED. Return value Returns a pointer to the new pixelmap, or NULL if unsuccessful. 4.1.1.4 BrPixelmapAllocateSub Syntax br_pixelmap * BrPixelmapAllocateSub(br_pixelmap *pm, br_uint_16 x, br_uint_16 y, br_uint_16 w, br_uint_16 h); Description Allocate a pixelmap as part of an existing pixelmap. The new pixelmap is clipped to the existing pixelmap. Arguments pm A pointer to an existing pixelmap. x X coordinate of the top left of the new pixelmap in the existing pixelmap. y Y coordinate of the top left of the new pixelmap in the existing pixelmap. w Width of the new pixelmap. h Height of the new pixelmap. Return value Returns a pointer to the new pixelmap, or NULL if unsuccessful. 4.1.1.5 Br#Free Syntax void BrMaterialFree(br_material *mat); void BrModelFree(br_model *model); void BrPixelmapFree(br_pixelmap *pmap); Description De-allocate a pixelmap, material or model and any associated memory. Arguments mat A pointer to a material. model A pointer to a model. pmap A pointer to a pixelmap. 4.1.2 Load/Save 4.1.2.1 Br#Load Syntax br_material * BrMaterialLoad(char *filename); br_model * BrModelLoad(char *filename); br_pixelmap * BrPixelmapLoad(char *filename); Description Load a material, a model or a pixelmap. Note that they are not added to the registry. Arguments *filename Name of the file containing the item to load. Return value Returns a pointer to the loaded item, or NULL if unsuccessful. See also Br#LoadMany Br#Save Br#SaveMany Br#Add Br#Remove Br#Update 4.1.2.2 Br#LoadMany Syntax br_uint_32 BrMaterialLoadMany(char *filename, br_material **materials, br_uint_16 num); br_uint_32 BrModelLoadMany(char *filename, br_model **models, br_uint_16 num); br_uint_32 BrPixelmapLoadMany(char *filename, br_pixelmap **pixelmaps, br_uint_16 num); Description Load a number of materials, models or pixelmaps. Note that they are not added to the registry. Arguments *filename Name of the file containing the items to load. materials A pointer to an array of pointers to materials, or NULL. models A pointer to an array of pointers to models, or NULL. pixelmaps A pointer to an array of pointers to pixelmaps, or NULL. num Maximum number of items to load. If NULL is passed as the second argument, the items are still loaded but must be referenced subsequently by name. Return value Returns the number of items loaded successfully. The pointer array is filled with pointers to the loaded items. 4.1.2.3 Br#Save Syntax br_uint_32 BrMaterialSave(char *filename, br_material *material); br_uint_32 BrModelSave(char *filename, br_model *model); br_uint_32 BrPixelmapSave(char *filename, br_pixelmap *pixelmap); Description Save a material, model or pixelmap to a file. Arguments *filename Name of the file to save the item to. material A pointer to a material. model A pointer to a model. pixelmap A pointer to a pixelmap. Return value Returns NULL if the item could not be saved. 4.1.2.4 Br#SaveMany Syntax br_uint_32 BrMaterialSaveMany(char *filename, br_material **materials, br_uint_16 num); br_uint_32 BrModelSaveMany(char *filename, br_model **models, br_uint_16 num); br_uint_32 BrPixelmapSaveMany(char *filename, br_pixelmap **pixelmaps, br_uint_16 num); Description Save a number of materials, models or pixelmaps to a file. Arguments *filename Name of the file to save the items to. materials A pointer to an array of pointers to materials. models A pointer to an array of pointers to models. pixelmaps A pointer to an array of pointers to pixelmaps. num Number of items to save. If NULL is passed as the second argument, all registered materials, models or pixelmaps are saved. Return value Returns the number of items saved successfully. 4.1.3 Add/Remove 4.1.3.1 Br#Add Syntax br_material * BrMaterialAdd(br_material *material); br_model * BrModelAdd(br_model *model); br_pixelmap * BrMapAdd(br_pixelmap *pixelmap); br_pixelmap * BrTableAdd(br_pixelmap *pixelmap); Description Add a material, model, map or table to the registry, updating them as necessary. All items must be added to the registry before they are used subsequently. Arguments material A pointer to a material. model A pointer to a model. pixelmap A pointer to a pixelmap. Return value Returns a pointer to the added item, else NULL if unsuccessful. See also Br#Update Br#AddMany Br#Load Br#Find Br#Remove 4.1.3.2 Br#AddMany Syntax br_uint_32 BrMaterialAddMany(br_material **materials, int n); br_uint_32 BrModelAddMany(br_model **models, int n); br_uint_32 BrMapAddMany(br_pixelmap **pixelmaps, int n); br_uint_32 BrTableAddMany(br_pixelmap **pixelmaps, int n); Description Add a number of materials, models, maps or tables to the registry, updating them as necessary. Arguments materials A pointer to an array of pointers to materials. models A pointer to an array of pointers to models. pixelmaps A pointer to an array of pointers to pixelmaps. n Number of items to add to the registry. Return value Returns the number of items added successfully. See also Br#Update Br#Add Br#Remove Br#RemoveMany 4.1.3.3 Br#Remove Syntax br_material * BrMaterialRemove(br_material *material); br_model * BrModelRemove(br_model *model); br_pixelmap * BrMapRemove(br_pixelmap *pixelmap); br_pixelmap * BrTableRemove(br_pixelmap *pixelmap); Description Remove a material, model, map or table from the registry. Arguments material A pointer to a material. model A pointer to a model. pixelmap A pointer to a pixelmap. Return value Returns a pointer to the item removed. See also Br#Add 4.1.3.4 Br#RemoveMany Syntax br_uint_32 BrMaterialRemoveMany(br_material **materials, int n); br_uint_32 BrModelRemoveMany(br_model **models, int n); br_uint_32 BrMapRemoveMany(br_pixelmap **pixelmaps, int n); br_uint_32 BrTableRemoveMany(br_pixelmap **pixelmaps, int n); Description Remove a number of materials, models, maps or tables from the registry. Arguments materials A pointer to an array of pointers to materials. models A pointer to an array of pointers to models. pixelmaps A pointer to an array of pointers to pixelmaps. n Number of items to remove from the registry. Return value Returns the number of items removed successfully. See also Br#AddMany 4.1.4 Find 4.1.4.1 Br#Find Syntax br_material * BrMaterialFind(char *pattern); br_model * BrModelFind(char *pattern); br_pixelmap * BrMapFind(char *pattern); br_pixelmap * BrTableFind(char *pattern); Description Find a material, model, map or table in the registry by name. A callback function can be setup to be called if the search is unsuccessful. The search pattern can include the standard wildcards '*' and '?'. Arguments *pattern Search pattern. Return value Returns a pointer to the item if found, otherwise NULL. If a callback exists and is called, the callback's return value is returned. See also Br#FindHook Br#FindMany 4.1.4.2 Br#FindMany Syntax br_uint_32 BrMaterialFindMany(char *pattern, br_material **materials, int max); br_uint_32 BrModelFindMany(char *pattern, br_model **models, int max); br_uint_32 BrMapFindMany(char *pattern, br_pixelmap **pixelmaps, int max); br_uint_32 BrTableFindMany(char *pattern, br_pixelmap **pixelmaps, int max); Description Find a number of materials, models, maps or tables in the registry by name. The search pattern can include the standard wildcards '*' and '?'. Arguments *pattern Search pattern. materials A pointer to an array of pointers to materials. models A pointer to an array of pointers to models. pixelmaps A pointer to an array of pointers to pixelmaps. max Maximum number of items to find. Return value Returns the number of items found. The pointer array is filled with pointers to the found items. See also Br#Find Br#FindHook 4.1.4.3 Br#FindHook Syntax br_material_find_cbfn * BrMaterialFindHook(br_material_find_cbfn *hook); br_model_find_cbfn * BrModelFindHook(br_model_find_cbfn *hook); br_map_find_cbfn * BrMapFindHook(br_map_find_cbfn *hook); br_table_find_cbfn * BrTableFindHook(br_table_find_cbfn *hook); Description Functions to set up a callback. If Br#Find is unsuccessful and a callback has been set up, the callback is passed the search pattern as its only argument. The callback should then return a pointer to a substitute or default item. For example, a callback could be set up to return a default material if the desired material cannot be found in the registry. As demonstrated in the example, the BR_CALLBACK macro must be used. This is to ensure compiler compatibility. Arguments hook A pointer to a callback function. Return value Returns a pointer to the old callback function. Example br_model BR_CALLBACK *test_callback(char *pattern) { br_model *default_model; ... return(default_model); } ... { br_model *model; ... BrModelFindHook(&test_callback); model = BrModelFind("non_existant_model"); } 4.1.5 Enumeration 4.1.5.1 Br#Count Syntax br_uint_32 BrMaterialCount(char *pattern); br_uint_32 BrModelCount(char *pattern); br_uint_32 BrMapCount(char *pattern); br_uint_32 BrTableCount(char *pattern); Description Count the number of registered items whose names match a given search pattern. The search pattern can include the standard wildcards '*' and '?'. Arguments *pattern Search pattern. Return value Returns the number of items matching the search pattern. See also Br#Enum Br#Find 4.1.5.2 Br#Enum Syntax br_uint_32 BrMaterialEnum(char *pattern, br_material_enum_cbfn *callback, void *arg); void *arg); br_uint_32 BrModelEnum(char *pattern, br_model_enum_cbfn *callback, void *arg); br_uint_32 BrMapEnum(char *pattern,br_map_enum_cbfn *callback, void *arg); br_uint_32 BrTableEnum(char *pattern, br_table_enum_cbfn *callback, void *arg); Description Calls a callback function for every item matching a given search pattern. The callback 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 wildcards '*' and '?'. The callback itself returns a br_uint_32 value. The enumeration will halt at any stage if the return value is non-zero. As demonstrated in the example, the BR_CALLBACK macro must be used to ensure compiler compatibility. Arguments *pattern Search pattern. callback A pointer to a callback function. arg An optional argument to pass to the callback function. Return value Returns the first non-zero callback return value, or zero if all matching items are enumerated. Example br_uint_32 BR_CALLBACK test_callback(br_material *mat, void *arg) { br_uint_32 count; ... return(count); } ... { br_uint_32 enum; ... enum = BrMaterialEnum("material",&test_callback,NULL); } 4.1.6 Update 4.1.6.1 Br#Update Syntax void BrMaterialUpdate(br_material *material, br_uint_16 flags); void BrModelUpdate(br_model *model, br_uint_16 flags); void BrMapUpdate(br_pixelmap *pixelmap, br_uint_16 flags); void BrTableUpdate(br_pixelmap *pixelmap, br_uint_16 flags); Description Update a material, model, map or table. For example, the user may wish to create a model whilst an application is running, by supplying lists of vertices and faces. Before it can be rendered, the model's surface normals, radius, bounding box, and other data structures must be pre-calculated, using the BrModelUpdate function. Similarly, if the vertex positions are changed subsequently whilst the application is running, the model will need to be updated before it is rendered again. Items are automatically updated when they are added to the registry. Arguments material A pointer to a material. model A pointer to a model. pixelmap A pointer to a map or table. flags Update flags (see section 4.1.6.2). See also Br#Add 4.1.6.2 Update flags Description Item update flags. In general, BR_#_ALL should be used. If, for example, the vertices of a prepared model are moved but the topology of the model is left unchanged, BR_MODU_NORMALS|BR_MODU_BOUNDING_BOX will suffice. Definitions BR_MODU_NORMALS Compute surface normals for the model. BR_MODU_EDGES Compute edges. BR_MODU_RADIUS Compute the model's bounding radius. BR_MODU_GROUPS Group all polygons which share the same material. BR_MODU_BOUNDING_BOX Compute the model's bounding box. BR_MODU_MATERIALS Update the model's materials. BR_MODU_ALL Do all of the above. BR_MATU_ALL Update material. BR_MAPU_ALL Update map. BR_TABU_ALL Update table. See also Br#Prepare ΓòÉΓòÉΓòÉ 6. 5. The Support Library ΓòÉΓòÉΓòÉ The support library plays an important role in BRender's platform independence. BRender applications should not use native C library functions for many operations, primarily those involving file systems, memory allocation and error handling. Instead, they should use the support library functions. By default, many of these are simply wrappers for the standard C calls. Functions are provided to install new filesystem, memory management and error handling functions, and the user can tailor individual calls to suit specific platforms. 5.1 General Functions 5.1.1.1 BrQsort Syntax typedef int br_qsort_cbfn(const void *, const void *); void BrQsort(void *basep, unsigned int nelems, unsigned int size, br_qsort_cbfn *comp); Description BRender's quick sort. By default, this is just a wrapper for the standard C library call. Arguments basep A pointer to the array to be sorted. nelems Number of elements in the array. size Size of each element (in bytes). comp A pointer to a comparison function. 5.1.1.2 BrBlockCopy Syntax void BrBlockCopy(void *dest_ptr, void *src_ptr, int dwords); Description Copy a block of memory. The source and destination blocks must not overlap. Arguments dest_ptr Destination pointer. src_ptr Source pointer. dwords Size of block to copy (number of 32-bit words). See also BrBlockFill 5.1.1.3 BrBlockFill Syntax void BrBlockFill(void *dest_ptr, int value, int dwords); Description Fast fill a block of memory. Arguments dest_ptr A pointer to the block to be filled. value Value to fill the block with. dwords Size of block (number of 32-bit words). See also BrBlockCopy ΓòÉΓòÉΓòÉ 6.1. 5.2 Error Handling ΓòÉΓòÉΓòÉ 5.2.1.1 Error handling macros Syntax #define BR_ERROR(s) BrError(s) #define BR_ERROR0(s) BrError(s) #define BR_ERROR1(s,a) BrError(s,a) #define BR_ERROR2(s,a,b) BrError(s,a,b) #define BR_ERROR3(s,a,b,c) BrError(s,a,b,c) #define BR_ERROR4(s,a,b,c,d) BrError(s,a,b,c,d) #define BR_ERROR5(s,a,b,c,d,e) BrError(s,a,b,c,d,e) #define BR_ERROR6(s,a,b,c,d,e,f) BrError(s,a,b,c,d,e,f) #define BR_WARNING(s) BrWarning(s) #define BR_WARNING0(s) BrWarning(s) #define BR_WARNING1(s,a) BrWarning(s,a) #define BR_WARNING2(s,a,b) BrWarning(s,a,b) #define BR_WARNING3(s,a,b,c) BrWarning(s,a,b,c) #define BR_WARNING4(s,a,b,c,d) BrWarning(s,a,b,c,d) #define BR_WARNING5(s,a,b,c,d,e) BrWarning(s,a,b,c,d,e) #define BR_WARNING6(s,a,b,c,d,e,f) BrWarning(s,a,b,c,d,e,f) #define BR_FATAL(s) BrFatal(__FILE__,__LINE__,s) #define BR_FATAL0(s) BrFatal(__FILE__,__LINE__,s) #define BR_FATAL1(s,a) BrFatal(__FILE__,__LINE__,s,a) #define BR_FATAL2(s,a,b) BrFatal(__FILE__,__LINE__,s,a,b) #define BR_FATAL3(s,a,b,c) BrFatal(__FILE__,__LINE__,s,a,b,c) #define BR_FATAL4(s,a,b,c,d) BrFatal(__FILE__,__LINE__,s,a,b,c,d) #define BR_FATAL5(s,a,b,c,d,e) BrFatal(__FILE__,__LINE__,s,a,b,c,d,e) #define BR_FATAL6(s,a,b,c,d,e,f) BrFatal(__FILE__,__LINE__, s,a,b,c,d,e,f) Description Macros for reporting errors, warnings and fatal errors. Error handling can be turned off at compile time by redefining these macros. Arguments s A standard printf format string. a,b,c,d,e,f Arguments corresponding with the format string. 5.2.2 Functions 5.2.2.1 BrErrorHandlerSet Syntax br_errorhandler * BrErrorHandlerSet(br_errorhandler *neweh); Description Install a new error handler. Arguments neweh A pointer to an instance of a br_errorhandler structure. Return value Returns a pointer to the old error handler. See also br_errorhandler 5.2.3 Datatypes 5.2.3.1 br_errorhandler Syntax typedef struct br_errorhandler { char *identifier; void (*warning)(char *message); void (*error)(char *message); } br_errorhandler; Description BRender routes error and warning handling calls through an instance of this structure. Members *identifier Name of the error handler. warning A pointer to a warning handler. error A pointer to an error handler. See also BrErrorHandlerSet ΓòÉΓòÉΓòÉ 6.2. 5.3 Big/Little Endian Macros ΓòÉΓòÉΓòÉ 5.3.1.1 Conversion macros Syntax #define BrNtoHF(x) #define BrNtoHL(x) #define BrNtoHS(x) #define BrHtoNF(x) #define BrHtoNL(x) #define BrHtoNS(x) Description Macros to convert between big and little endian byte orderings. The naming convention is as follows: N for network order, H for host order, F for float, L for long integer and S for short integer. ΓòÉΓòÉΓòÉ 6.3. 5.4 File System Support ΓòÉΓòÉΓòÉ 5.4.1 Import functions 5.4.1.1 BrFmtASCLoad Syntax br_uint_32 BrFmtASCLoad(char *name, br_model **mtable, int max_models); Description Import 3D studio models (geometry only). The models are neither updated nor registered. Arguments *name Name of the file containing the models. mtable A pointer to an array of pointers to models, which will be filled as they are imported. If NULL, the models are still imported, but must be referenced subsequently by name. max_models The maximum number of models to import. Return value Returns the number of successfully imported models. 5.4.1.2 BrFmtNFFLoad Syntax br_model * BrFmtNFFLoad(char *name); Description Import a model expressed in the Neutral File Format. The model is neither updated nor registered. Arguments *name Name of the file containing the model. Return value Returns a pointer to the imported model, or NULL if it could not be imported. 5.4.1.3 BrFmtScriptMaterialLoad Syntax br_material * BrFmtScriptMaterialLoad(char *filename); Description Load a material from a material script. Note that all maps and tables in a script should be already loaded and registered. If some of them are not, this function can be combined with Br#FindHook to facilitate rapid setup of materials with textures. Arguments *filename Name of the file containing the script. Return value Returns a pointer to the loaded material, or NULL if unsuccessful. Example Material scripts are formatted as follows: # Comment # # Fields may be given in any order or omitted # (a sensible default will be supplied) # Extra white spaces are ignored material = [ name = "foo"; flags=[light,prelit,smooth,environment,environment_local,perspective, decal,always_visible,two_sided,force_z_0]; colour = [10,10,20]; ambient = 0.10; diffuse = 0.70; specular = 0.40; power = 30; map_transform = [[1,0], [0,1], [0,0]]; index_base = 0; index_range = 0; colour_map = "brick"; index_shade = "shade.tab"; ]; 5.4.1.4 BrFmtScriptMaterialLoadMany Syntax br_uint_32 BrFmtScriptMaterialLoadMany(char *filename, br_material **materials, br_uint_32 num); Description Load a number of materials from a material script. Arguments *filename Name of the file containing a number of concatenated material script entries. materials A pointer to an array of pointers to materials. num Maximum number of materials to load. Return value Return the number of materials loaded successfully. The pointer array is filled with pointers to the loaded materials. 5.4.1.5 BrFmt#Load Syntax br_pixelmap * BrFmtBMPLoad(char *name, br_uint_32 flags); br_pixelmap * BrFmtTGALoad(char *name, br_uint_32 flags); br_pixelmap * BrFmtGIFLoad(char *name, br_uint_32 flags); br_pixelmap * BrFmtIFFLoad(char *name, br_uint_32 flags); Description Load a pixelmap in the BMP, TGA, GIF or IFF format. Arguments *name Name of the file containing the pixelmap. flags Either BR_PMT_RGBX_888 or BR_ PMT_RGBA_8888, when the source pixelmap uses 32 bits per pixel. Zero otherwise. Return value Returns a pointer to the loaded pixelmap. 5.4.2 File system functions 5.4.2.1 Standard functions Syntax br_uint_32 BrFileAttributes(void); int BrFileEof(void *f); int BrFileGetChar(void *f); int BrFileGetLine(char *buf, br_size_t buf_len, void * f); int BrFilePrintf(void *f, char *fmt, ...); int BrFileRead(void *buf, int size, int n,void *f); int BrFileWrite(void *buf, int size, int n, void *f); void * BrFileOpenRead(char *name, br_size_t n_magics, br_mode_test_cbfn *mode_test, int *mode_result); void * BrFileOpenWrite(char *name, int text); void BrFileAdvance(long int count, void *f); void BrFileClose(void *f); void BrFilePutChar(int c, void *f); void BrFilePutLine(char *buf, void * f); Description BRender 's file system function calls, corresponding with the standard C library functions. By default, BRender's functions are mapped to the C library functions. 5.4.2.2 BrFilesystemSet Syntax br_filesystem * BrFilesystemSet(br_filesystem *newfs); Description Install a new file system. Arguments newfs A pointer to an instance of a br_filesystem structure. Return value Returns a pointer to the old br_filesystem structure. See also br_filesystem 5.4.2.3 BrWriteModeSet Syntax int BrWriteModeSet(int mode); Description Set the current write mode to plain text or binary (when saving actors, materials, models, pixelmaps etc.). Arguments mode Write mode. Either BR_FS_MODE_TEXT or BR_FS_MODE_BINARY. Return value Returns the old write mode. See also Br#Load Br#Save 5.4.3 Datatypes 5.4.3.1 br_filesystem Structure typedef unsigned int br_size_t; typedef struct br_filesystem { char *identifier; br_uint_32 (*attributes)(void); void * (*open_read)(char *name, br_size_t n_magics, br_mode_test_cbfn *mode_test, int *mode_result); void * (*open_write)(char *name, int text); void (*close)(void * f); int (*eof)(void * f); int (*getchr)(void * f); void (*putchr)(int c, void * f); br_size_t (*read) (void *buf, br_size_t size, unsigned int nelems, void * f); br_size_t (*write)(void *buf, br_size_t size, unsigned int nelems, void * f); br_size_t (*getline)(char *buf, br_size_t buf_len, void * f); void (*putline)(char *buf, void * f); void (*advance)(br_size_t count, void * f); } br_filesystem; Description BRender routes all file system calls through an instance of this structure. The syntax corresponds exactly with the standard C library calls. This allows the user to tailor BRender's file system characteristics to suit any platform. As demonstrated in the example, the BR_CALLBACK macro must be used to ensure compiler compatibility. Members *identifier File system name. attributes A pointer to a function inquiring file system attributes. Such a function should return a value based on the following flags: BR_FS_ATTR_READABLE BR_FS_ATTR_WRITEABLE BR_FS_ATTR_HAS_TEXT BR_FS_ATTR_HAS_BINARY BR_FS_ATTR_HAS_ADVANCE open_read A pointer to a function to open a file for reading. open_write A pointer to a function to open a file for writing. close A pointer to a function to close an opened file. eof A pointer to a function to check for end of file. getchr A pointer to a function to read one character. putchr A pointer to a function to write one character. read A pointer to a function to read a block. write A pointer to a function to write a block. getline A pointer to a function to read a line of text. putline A pointer to a function to write a line of text. advance A pointer to a function to advance through a stream. See also BrFilesystemSet Example int BR_CALLBACK example_eof(void *f) { int flag ... return(flag); } { br_filesystem example_filesystem; example_filesystem.eof = &example_eof; ... BrFilesystemSet(&example_filesystem); } ΓòÉΓòÉΓòÉ 6.4. 5.5 Memory Management Functions ΓòÉΓòÉΓòÉ 5.5.1 Standard memory management functions 5.5.1.1 BrMemAllocate Syntax typedef unsigned int br_size_t; void * BrMemAllocate(br_size_t size, br_uint_8 type); Description Allocate memory. Arguments size Size of memory block to be allocated. type Memory type (see section 5.5.2.2). Return value Returns a pointer to the allocated memory, or NULL is unsuccessful. 5.5.1.2 BrMemCalloc Syntax typedef unsigned int br_size_t; void * BrMemCalloc(int nelems, br_size_t size, br_uint_8 type); Description Allocate and clear memory. Arguments nelems Number of elements to allocate. size Size of each element. type Memory type (see section 5.5.2.2). Return value Returns a pointer to the allocated memory, or NULL is unsuccessful. 5.5.1.3 BrMemFree Syntax void BrMemFree(void *block); Description De-allocate memory. Arguments block A pointer to the block of memory to de-allocate. 5.5.1.4 BrMemInquire Syntax typedef unsigned int br_size_t; br_size_t BrMemInquire(br_uint_8 type); Description Find the amount of memory available of a given type. Arguments type Memory type (see section 5.5.2.2). Return value Returns memory available in bytes. 5.5.1.5 BrMemStrDup Syntax char * BrMemStrDup(char *str); Description Duplicate a string. Arguments str A pointer to the source string. Return value Returns a pointer to the new copy of the string. 5.5.1.6 BrAllocatorSet Syntax br_allocator * BrAllocatorSet(br_allocator *newal); Description Install a new set of memory allocation/de-allocation functions. Arguments newal A pointer to an instance of a br_allocator structure. Return value Returns a pointer to the old br_allocator structure. See also br_allocator 5.5.2 Datatypes 5.5.2.1 br_allocator Syntax typedef struct br_allocator { char *identifier; void * (*allocate)(br_size_t size, br_uint_8 type); void (*free)(void *block); br_size_t (*inquire)(br_uint_8 type); } br_allocator; Description BRender routes memory allocation and de-allocation through an instance of this structure. As demonstrated in the example, the BR_CALLBACK macro must be used to ensure compiler compatiblilty. Members *identifier Allocator name. allocate A pointer to a memory allocator. free A pointer to a memory de-allocator. inquire A pointer to a memory inquire. Example void BR_CALLBACK example_free(void *block) { ... } { br_allocator example_allocator; example_allocator.free = &example_free; ... BrAllocatorSet(&example_allocator); } 5.5.2.2 Memory classes Decsription BRender memory class definitions. User defined classes begin at BR_MEMORY_APPLICATION and end at BR_MEMORY_MAX. Definitions BR_MEMORY_SCRATCH BR_MEMORY_PIXELMAP BR_MEMORY_PIXELS BR_MEMORY_VERTICES BR_MEMORY_FACES BR_MEMORY_GROUPS BR_MEMORY_MODEL BR_MEMORY_MATERIAL BR_MEMORY_MATERIAL_INDEX BR_MEMORY_ACTOR BR_MEMORY_PREPARED_VERTICES BR_MEMORY_PREPARED_FACES BR_MEMORY_LIGHT BR_MEMORY_CAMERA BR_MEMORY_BOUNDS BR_MEMORY_CLIP_PLANE BR_MEMORY_STRING BR_MEMORY_REGISTRY BR_MEMORY_TRANSFORM BR_MEMORY_RESOURCE_CLASS BR_MEMORY_FILE BR_MEMORY_ANCHOR BR_MEMORY_POOL BR_MEMORY_RENDER_MATERIAL BR_MEMORY_APPLICATION = 0x80 BR_MEMORY_MAX = 0x100 ΓòÉΓòÉΓòÉ 6.5. 5.6 Block pool memory management functions ΓòÉΓòÉΓòÉ BRender's block pool allocation functions facilitate rapid allocation and de-allocation of blocks of memory. A large 'pool' of memory is allocated and split into a number of smaller 'blocks'. BRender maintains a record of their usage. If a new block is requested but none is available, BRender will automatically expand the pool as necessary. 5.6.1 Functions 5.6.1.1 BrPoolAllocate Syntax br_pool * BrPoolAllocate(int block_size, int chunk_size, br_uint_8 mem_type); Description Create a new block pool. Arguments block_size The size of each block, in bytes. chuck_size The number of block to allocate each time the pool becomes full. mem_type Memory type (see section 5.5.2.2). Return value Returns a pointer to the new pool, or NULL if it could not be created. 5.6.1.2 BrPoolFree Syntax void BrPoolFree(br_pool *pool); Description De-allocate an entire pool, thereby losing any blocks it may contain. Arguments pool A pointer to the pool to be de-allocated. 5.6.1.3 BrPoolEmpty Syntax void BrPoolEmpty(br_pool *pool); Description Mark all blocks in a pool as unused. Arguments pool A pointer to the pool to be emptied. 5.6.1.4 BrPoolBlockAllocate Syntax void * BrPoolBlockAllocate(br_pool *pool); Description Allocate a block from a pool. If the pool is full, it will expand as necessary. Arguments pool A pointer to the relevent pool. Return value Returns a pointer to the allocated block, or NULL if unsuccessful. 5.6.1.5 BrPoolBlockFree Syntax void BrPoolBlockFree(br_pool *pool, void *b); Description De-allocate a block from a pool. Arguments pool A pointer to the relevent pool. b A pointer to the block to de-allocate. ΓòÉΓòÉΓòÉ 6.6. 5.7 Resource management functions ΓòÉΓòÉΓòÉ Conceptually, resources are a layer on top of the standard memory management functions that allow blocks of memory to be associated in a hierarchy. For instance, freeing a parent block will also free its children. Each class of resource is kept in a registry (in a manner identical to materials, pixelmaps, etc.). Moreover, a resource class can have a 'destructor' function invoked whenever a block in the class is freed. Due to the way in which resources are used internally, models must be created by BRender, either by a Br#Load operation or a Br#Allocate. This is not necessary for actors, and actor structures can be embedded in user-managed structures. 5.7.1 Datatypes 5.7.1.1 Resource class Structure typedef struct br_resource_class { char *identifier; br_uint_8 res_class; br_resourcefree_cbfn *free_cb; } br_resource_class; Description BRender's resource class structure. Members *identifier Resource class name. res_class Resource class (see section 5.5.2.2). free_cb A pointer to a resource class destructor, called whenever a resource block in the class is freed. See also BrResFree 5.7.2 Resource allocation functions 5.7.2.1 BrResAllocate Syntax void * BrResAllocate(void *vparent, br_size_t size, int res_class); Description Allocate a new resource block of a given class. Arguments vparent A pointer to a parental resource block, or NULL if it will have no parent. size Size of block in bytes. res_class Resource class (see section 5.5.2.2). Return value Returns a pointer to the allocated resource block. 5.7.2.2 BrResFree Syntax void BrResFree(void *vres); Description Free a resource block, and any child resources it has. If any resource classes have destructors, they are invoked when appropriate. Arguments vres A pointer to a resource block. Example void BR_CALLBACK example_destructor(void *res, br_uint_8 res_class , br_size_t size) { ... } #define EXAMPLE_CLASS (BR_MEMORY_ APPLICATION + 1) { void *ptr; br_resource_class example; example.identifier = "class_name" ; example.res_class = EXAMPLE_CLASS; example.free_cb = &example_destructor; ... BrResClassAdd(&example); /* Add resource class to registry */ ptr = BrResAllocate(NULL,1024,EXAMPLE_CLASS); BrResFree(ptr); /* Destructor is invoked */ } See also BrResClassAdd br_resource_class 5.7.2.3 BrResStrDup Syntax char * BrResStrDup(void *vparent, char *str); Description Allocate a resource block and copy a string into it. Arguments vparent A pointer to a parental resource block. str A pointer to the source string. Return value Returns a pointer to the allocated resource block. 5.7.2.4 BrResAdd Syntax void * BrResAdd(void *vparent, void *vres); Description Add a resource block as a child of another. Arguments vparent A pointer to the parent resource block. vres A pointer to the child resource block. Return value Returns a pointer to the child resource block. 5.7.2.5 BrResRemove Syntax void * BrResRemove(void *vres); Description Remove a resource block from a parent. Arguments vres A pointer to the resource block to be removed. Return value Returns a pointer to the removed resource block. 5.7.2.6 BrResClass Syntax br_uint_8 BrResClass(void *vres); Description Find the class of a given resource block. Arguments vres A pointer to a resource block. Return value Returns the resource class (see section 5.5.2.2). 5.7.2.7 BrResSize Syntax br_uint_32 BrResSize(void *vres); Description Find the size of a given resource block. Arguments vres A pointer to a resource block. Return value Returns the size of the resource block in bytes. 5.7.2.8 BrResChildEnum Syntax br_uint_32 BrResChildEnum(void *vres, br_resenum_cbfn *callback, void *arg); Description Invoke a callback function for each child of a resource block. The callback is passed a pointer to each child, and its second argument is an optional pointer supplied by the user. The callback itself returns a br_uint_32 value. The enumeration will halt at any stage if the return value is non-zero. As demonstrated in the example, the BR_CALLBACK macro must be used to ensure compiler compatibility. Arguments vres A pointer to a resource block. callback A pointer to a callback function. arg An optional argument to pass to the callback function. Return value Returns the first non-zero callback return value, or zero if all children are enumerated. Example br_uint_32 example_callback(void *vres, void *arg) { br_uint_32 value; ... return(value); } { br_uint_32 ev; void *rblock; ... ev = BrResChildEnum(rblock,&example_callback,NULL); } 5.7.3 Resource class registry functions 5.7.3.1 BrResClassAdd Syntax br_resource_class * BrResClassAdd(br_resource_class *rclass); Description Add a resource class to the registry. Arguments rclass A pointer to a resource class. Return value Returns a pointer to the added resource class, or NULL if unsuccessful. 5.7.3.2 BrResClassAddMany Syntax br_uint_32 BrResClassAddMany(br_resource_class **items, int n); Description Add a number of resource classes to the registry. Arguments items A pointer to an array of pointers to resource classes. n Number of resource classes to add to the registry. Return value Returns the number of resource classes successfully added to the registry. 5.7.3.3 BrResClassRemove Syntax br_resource_class * BrResClassRemove(br_resource_class *rclass); Description Remove a resource class from the registry. Arguments rclass A pointer to a resource class. Return value Returns a pointer to the removed resource class. 5.7.3.4 BrResClassRemoveMany Syntax br_uint_32 BrResClassRemoveMany(br_resource_class **items, int n); Description Remove a number of resource classes from the registry. Arguments items A pointer to an array of pointers to resource classes. n Number of resource classes to remove from the registry. Return value Returns the number of resource classes successfully removed from the registry. 5.7.3.5 BrResClassFind Syntax br_resource_class * BrResClassFind(char *pattern); Description Find a resource class in the registry by name. A callback function can be set up to be called if the search is unsuccessful. The search pattern can include the standard wildcards '*' and '?'. Arguments *pattern Search pattern. Return value Returns a pointer to the resource class if found, otherwise NULL. If a callback exists and is called, the callback's return value is returned. 5.7.3.6 BrResClassFindMany Syntax br_uint_32 BrResClassFindMany(char *pattern, br_resource_class **items, int max); Description Find a number of resource classes in the registry by name. The search pattern can include the standard wildcards '*' and '?'. Arguments *pattern Search pattern. items A pointer to an array of pointers to resource classes. max The maximum number of resource classes to find. Return value Returns the number of resource classes found. The pointer array is filled with pointers to the resource classes. 5.7.3.7 BrResClassFindHook Syntax br_resclass_find_cbfn * BrResClassFindHook(br_resclass_find_cbfn *hook); Description Set up a resource class find callback. If BrResClassFind is unsuccessful and a callback has been set up, the callback is passed the search pattern as its only argument. The callback should then return a pointer to a substitute or default resource class. Arguments hook A pointer to a callback function. Return value Returns a pointer to the old callback function. Example br_resource_class BR_CALLBACK *example_callback(char *pattern) { br_resource_class default; ... return(&default); } { br_resource_class *rc; ... BrResClassFindHook(&example_callback); rc = BrResClassFind("non_existant_class"); } 5.7.3.8 BrResClassCount Syntax br_uint_32 BrResClassCount(char *pattern); Description Count the number of resource classes in the registry whose names match a given search pattern. The search pattern can include the standard wildcards '*' and '?'. Arguments *pattern Search pattern. Return value Returns the number of resource classes matching the search string. 5.7.3.9 BrResClassEnum Syntax br_uint_32 BrResClassEnum(char *pattern, br_resclass_enum_cbfn *callback, void *arg); Description Call a callback function for every resource class matching a given search pattern. The callback is passed a pointer to each matching resource class, and its second argument is an optional pointer supplied by the user. The search pattern can include the standard wildcards '*' and '?'. The callback itself returns a br_uint_32 value. The enumeration will halt at any stage if the return value is non-zero. Arguments *pattern Search pattern. callback A pointer to a callback function. arg An optional argument to pass to the callback function. Return value Returns the first non-zero callback return value, of zero if all resource classes are enumerated. Example br_uint_32 BR_CALLBACK example_callback(br_resource_class *item, void *arg) { br_uint_32 value; ... return(value); } { br_uint_32 ev; ... ev = BrResClassEnum("pattern",&example_callback,NULL); } ΓòÉΓòÉΓòÉ 7. 6. The Maths Library - Overview ΓòÉΓòÉΓòÉ BRender provides substantial support for many mathematical primitives, namely: scalars, angles, vectors, matrices, quaternions and Euler angles. Scalars are BRender's own representation of real numbers, and most other objects are built from them. The libraries provide efficient routines for most mathematical operations relevant to 3D graphics. ΓòÉΓòÉΓòÉ 7.1. 6.1 Fixed and floating point representations ΓòÉΓòÉΓòÉ To take best advantage of platform specific maths hardware, and to increase speed generally, BRender can use either a fixed or floating point representation in the majority of its maths operations. In fact, BRender has two math libraries: fixed and floating point. They have the same API and the same functionality. A compiler directive specifying the library is set and BRender takes care of the rest. To be flexible in this way, BRender defines its own numerical representations: br_scalar, br_fraction and br_ufraction. If the floating point library is used, they are all floating point numbers. If the fixed point library is used, they are all fixed point numbers. A well-written BRender program will work under either representation. In C, this kind of flexibility is possible only with widespread use of macros, to insert seamlessly alternate sections of code according to which library is in use. It is vital to use the macros and functions provided wherever possible. There are macros for all common arithmetic operations, for the static initialisation of variables, and many specialised functions relevent to transformations and 3D graphics. Throughout this chapter, the '#' symbol is used as a wildcard. 6.1.1.1 Compiler directives for fixed/floating point Definitions BASED_FIXED BASED_FLOAT Description All BRender programs must be compiled with one of these directives in force. BASED_FIXED causes the use of fixed point numbers wherever possible. Alternatively, BASED_FLOAT causes the use of floating point numbers wherever an increase in accuracy can be made. In general, the fixed point library is faster than the floating point library. ΓòÉΓòÉΓòÉ 7.2. 6.2 Scalars ΓòÉΓòÉΓòÉ 6.2.1 Datatypes 6.2.1.1 br_scalar Definitions typedef long br_fixed_ls; typedef br_fixed_ls br_scalar; typedef float br_scalar; Description The br_scalar type is the general numerical representation used by BRender. Under the fixed point library, br_scalar is a 32 bit 16.16 fixed point number, and can represent numbers between approximately -32768 and +32768. Under the floating point library, br_scalar is a float, and can represent numbers between approximately -3.4e38 and +3.4e38. Associated macros BR_SCALAR(x) Converts constants to the br_scalar type. BR_SCALAR_EPSILON The smallest possible positive scalar value. BR_SCALAR_MAX The largest positive value a scalar can represent. BR_SCALAR_MIN The largest negative value a scalar can represent. Example br_scalar s=BR_SCALAR(100.0); See also BrFloatToScalar BrIntToScalar 6.2.1.2 br_fraction Definitions typedef short br_fixed_lsf; typedef br_fixed_lsf br_fraction; typedef float br_fraction; Description The br_fraction type can be used to represent numbers in the range [- 1,+1). Under the floating point library, br_fraction is a float. Under the fixed point library, br_fraction is a 16 bit signed fixed point number. Associated macros BR_FRACTION(x) Converts constants to the br_fraction type. Example br_fraction f=BR_FRACTION(-0.5); See also br_ufraction 6.2.1.3 br_ufraction Definitions typedef unsigned short br_fixed_luf; typedef br_fixed_luf br_ufraction; typedef float br_ufraction; Description The br_ufraction type can be used to represent numbers in the range [0,+1). Under the floating point library, br_ufraction is a float. Under the fixed point library, br_ufraction is a 16 bit unsigned fixed point number. Associated macros BR_UFRACTION(x) Converts constants to the br_ufraction type. Example br_ufraction f=BR_UFRACTION(0.005); See also br_fraction 6.2.2 Functions 6.2.2.1 Scalar conversion functions Syntax br_scalar BrAngleToScalar(br_angle a); br_scalar BrFixedToScalar(br_fixed_ls f); br_scalar BrFloatToScalar(float f); br_scalar BrFractionToScalar(br_fraction f); br_scalar BrIntToScalar(int i); br_scalar BrUFractionToScalar(br_ufraction f); br_angle BrScalarToAngle(br_scalar s); br_fixed_ls BrScalarToFixed(br_scalar s); br_float BrScalarToFloat(br_scalar s); br_fraction BrScalarToFraction(br_scalar s); int BrScalarToInt(br_scalar s); br_ufraction BrScalarToUFraction(br_scalar s); Description Functions implemented as macros to convert scalars to and from angle, fixed point, float and fraction types. See also Angle conversion functions 6.2.2.2 Fraction conversion functions Syntax br_scalar BrFractionToScalar(br_fraction f); br_fraction BrScalarToFraction(br_scalar s); br_scalar BrUFractionToScalar(br_ufraction uf); br_ufraction BrScalarToUFraction(br_scalar s); Description Functions implemented as macros to convert between fractions and scalars. 6.2.2.3 Scalar Arithmetic Syntax br_scalar BR_ADD(br_scalar a, br_scalar b); br_scalar BR_SUB(br_scalar a, br_scalar b); br_scalar BR_MUL(br_scalar a, br_scalar b); br_scalar BR_DIV(br_scalar a, br_scalar b); br_scalar BR_SQR(br_scalar a); br_scalar BR_RCP(br_scalar a); br_scalar BR_POW(br_scalar a, br_scalar b); br_scalar BR_SQRT(br_scalar a); br_scalar BR_MULDIV(br_scalar a, br_scalar b, br_scalar c); br_scalar BR_ABS(br_scalar a); Description Scalar arithmetic functions, implemented as macros. Arguments a,b,c Scalars. Return values BR_ADD returns a+b BR_SUB returns a-b BR_MUL returns a*b BR_DIV returns a/b BR_RCP returns 1/a BR_SQR returns a^2 BR_POW returns a^b BR_SQRT returns BR_MULDIV returns (a*b) / c BR_ABS returns |a| Example br_scalar s1,s2,s3,s4; ... s1=BR_ADD(s2,BR_POW(s3,s4)); See also BR_MAC# BR_LENGTH# 6.2.2.4 Multiply accumulate Syntax br_scalar BR_MAC2(br_scalar a, br_scalar b, br_scalar c, br_scalar d); br_scalar BR_MAC3(br_scalar a, br_scalar b, br_scalar c, br_scalar d, br_scalar e, br_scalar f); br_scalar BR_MAC4(br_scalar a, br_scalar b, br_scalar c, br_scalar d, br_scalar e, br_scalar f, br_scalar g, br_scalar h); br_scalar BR_FMAC2(br_fraction fa, br_scalar b, br _fraction fc, br_scalar d); br_scalar BR_FMAC3(br_fraction fa, br_scalar b, br _fraction fc, br_scalar d, br_fraction fe, br_scalar f); br_scalar BR_FMAC4(br_fraction fa, br_scalar b, br _fraction fc, br_scalar d, br_fraction fe, br_scalar f, br_fraction fg, br_scalar h); Description Functions to calculate the sum of the pairwise products of their arguments. The second group of functions takes fractional multiplicands. Arguments a,b,c,d,e,f,g,h Scalars. fa,fc,fe,fg Fractions. Return value Returns the sum of the pairwise products of arguments. Example br_scalar s1,s2,s3,s4,s5; ... s5=BR_MAC2(s1,s2,s3,s4); /* s5 = s1*s2 + s3*s4 */ See also BR_LENGTH# 6.2.2.5 Multiply accumulate and divide Syntax br_scalar BR_MAC2DIV(br_scalar a, br_scalar b, br_scalar c, br_scalar d, br_scalar s); br_scalar BR_MAC3DIV(br_scalar a, br_scalar b, br_scalar c, br_scalar d, br_scalar e, br_scalar f, br_scalar s); br_scalar BR_MAC4DIV(br_scalar a, br_scalar b, br_scalar c, br_scalar d, br_scalar e, br_scalar f, br_scalar g, br_scalar h, br_scalar s); Description Functions to calculate the sum of the pairwise products of their arguments and divide the result by a scalar. Arguments a,b,c,d,e,f,g,h Scalars. s A scalar divisor. Return values Returns the sum of the pairwise products of arguments, divided by the scalar s. Example br_scalar s1,s2,s3,s4,s5,s6; ... s6=BR_MAC2DIV(s1,s2,s3,s4,s5); /* s6 = (s1*s2 + s3*s4) / s5 */ See also BR_LENGTH# 6.2.2.6 Length Syntax br_scalar BR_LENGTH2(br_scalar a, br_scalar b); br_scalar BR_LENGTH3(br_scalar a, br_scalar b, br_scalar c); br_scalar BR_LENGTH4(br_scalar a, br_scalar b, br_scalar c, br_scalar d); br_scalar BR_RLENGTH2(br_scalar a, br_scalar b); br_scalar BR_RLENGTH3(br_scalar a, br_scalar b, br_scalar c); br_scalar BR_RLENGTH4(br_scalar a, br_scalar b, br_scalar c, br_scalar_d); Description Fast functions to compute the length and reciprocal length of a vector, given its constituent components. At the expense of accuracy, BR_RLENGTH# uses a reciprocal square root lookup-table to increase speed. Arguments a,b,c,d Scalars. Return values BR_LENGTH# returns the square root of the sum of its squared arguments. BR_RLENGTH# returns the reciprocal of the square root of the sum of its squared arguments. Example br_scalar sx,sy,sl; ... sl=BR_LENGTH2(sx,sy); /* length of line between (0,0) and (sx,sy) */ See also BR_SQR# 6.2.2.7 Constant operations Syntax br_scalar BR_CONST_MUL(br_scalar a, int b); br_scalar BR_CONST_DIV(br_scalar a, int b); Description Macros to multiply and divide scalars by integer constants. Arguments a A scalar. b An integer constant. Return values BR_CONST_MUL returns a*b BR_CONST_DIV returns a/b See also Scalar arithmetic 6.2.2.8 Sum of squares functions Syntax br_scalar BR_SQR2(br_scalar a, br_scalar b); br_scalar BR_SQR3(br_scalar a, br_scalar b, br_scalar c); br_scalar BR_SQR4(br_scalar a, br_scalar b, br_scalar c, br_scalar d); Description Macros to calculate the sum of squared arguments. Arguments a,b,c,d Scalars. Return values Returns the sum of squared arguments. See also BR_LENGTH# BR_MAC# ΓòÉΓòÉΓòÉ 7.3. 6.3 Integers ΓòÉΓòÉΓòÉ 6.3.1 Datatypes 6.3.1.1 br_int_# / br_uint_# Definitions typedef signed long br_int_32; typedef unsigned long br_uint_32; typedef signed short br_int_16; typedef unsigned short br_uint_16; typedef signed char br_int_8; typedef unsigned char br_uint_8; Description BRender's signed and unsigned integer types. 6.3.1.2 Integer conversion functions Syntax int BrFixedToInt(br_fixed_ls s) br_fixed_ls BrIntToFixed(int i) int BrScalarToInt(br_scalar s) br_scalar BrIntToScalar(int i) Description Macros to convert between scalars and integers, and fixed-point numbers and integers. ΓòÉΓòÉΓòÉ 7.4. 6.4 Angles ΓòÉΓòÉΓòÉ 6.4.1 Datatypes 6.4.1.1 br_angle Definition typedef fixed_luf br_angle; Description BRender's own angle representation. One complete revolution corresponds to the entire range of this datatype, and therefore repeated rotations will 'wrap around' correctly. Associated macros BR_ANGLE_DEG(x) Converts a constant angle from degrees to the br_angle type BR_ANGLE_RAD(x) Converts a constant angle from radians to the br_angle type. 6.4.2 Functions 6.4.2.1 Angle conversion functions Syntax br_scalar BrAngleToDegree(br_angle a) br_angle BrDegreeToAngle(br_scalar d) br_scalar BrAngleToRadian(br_angle a) br_angle BrRadianToAngle(br_scalar r) br_scalar BrAngleToScalar(br_angle a) br_angle BrScalarToAngle(br_scalar s) br_scalar BrDegreeToRadian(br_scalar d) br_scalar BrRadianToDegree(br_scalar r) Description These functions are implemented as macros and convert between different angle representations, namely: BRender's own angle representation br_angle, degrees and radians (given as scalars), and scalars themselves, where the range [0,1) corresponds to one complete rotation. Example br_angle a1,a2,a3,a4; ... a1=BR_ANGLE_DEG(90.0); /* a1 = a2 = a3 = a4 */ a2=BrDegreeToAngle(BR_SCALAR(90.0)); a3=BrRadianToAngle(BR_SCALAR(PI/2)); a4=BrScalarToangle(BR_SCALAR(0.25)); See also br_angle Scalar conversion functions 6.4.2.2 Trigonometry Syntax br_scalar BR_SIN(br_angle a); br_scalar BR_COS(br_angle a); br_angle BR_ASIN(br_scalar f); br_angle BR_ACOS(br_scalar f); br_angle BR_ATAN2(br_scalar x, br_scalar y); br_angle BR_ATAN2FAST(br_scalar x, br_scalar y); Description Standard trigonometric functions. BR_ATAN2FAST is a faster, but less accurate version of BR_ATAN2. Arguments BR_SIN and BR_COS both take one br_angle argument. BR_ASIN and BR_ACOS both take one br_scalar argument. BR_ATAN2 and BR_ATAN2FAST both take two br_scalar arguments. Return values BR_SIN and BR_COS return the sine and cosine of their argument, respectively. BR_ASIN and BR_ACOS return the arc-sine and arc-cosine of their argument, respectively. BR_ATAN2 and BR_ATAN2FAST both return the arc-tangent of their second argument divided by their first argument. See also br_angle ΓòÉΓòÉΓòÉ 7.5. 6.5 Euler Angles ΓòÉΓòÉΓòÉ 6.5.1 Datatypes 6.5.1.1 br_euler Structure typedef struct br_euler { br_angle a; br_angle b; br_angle c; br_uint_8 order; } br_euler; Description Euler angles can be used to represent the orientation of an object. Three separate rotations are applied in turn, in a specific order. Euler angles can be either static or relative. With relative euler angles, the rotations are performed around axes relative to the rotations already performed. With static euler angles, the rotations are performed around static axes. Members a First angle. b Second angle. c Third angle. order Static or relative rotation order (see section 6.5.1.2). See also br_angle Euler angle orderings 6.5.1.2 Euler angle orderings Description Definitions for Euler angle orderings. The first three letters indicate the axes and order in which rotations occurs. The last letter indicates whether the rotations are static or relative. Definitions BR_EULER_XYZ_S BR_EULER_XYX_S BR_EULER_XZY_S BR_EULER_XZX_S BR_EULER_YZX_S BR_EULER_YZY_S BR_EULER_YXZ_S BR_EULER_YXY_S BR_EULER_ZXY_S BR_EULER_ZXZ_S BR_EULER_ZYX_S BR_EULER_ZYZ_S BR_EULER_ZYX_R BR_EULER_XYX_R BR_EULER_YZX_R BR_EULER_XZX_R BR_EULER_XZY_R BR_EULER_YZY_R BR_EULER_ZXY_R BR_EULER_YXY_R BR_EULER_YXZ_R BR_EULER_ZXZ_R BR_EULER_XYZ_R BR_EULER_ZYZ_R See also br_euler br_angle 6.5.2 Functions 6.5.2.1 Euler angle conversion functions Syntax br_matrix34 * BrEulerToMatrix34(br_matrix34 *mat, br_euler *euler); br_matrix4 * BrEulerToMatrix4(br_matrix4 *mat, br_euler *euler); br_quat * BrEulerToQuat(br_quat *quat, br_euler *euler); br_euler * BrMatrix34ToEuler(br_euler *euler, br_matrix34 *mat); br_euler * BrMatrix4ToEuler(br_euler *euler, br_matrix4 *mat); br_euler * BrQuatToEuler(br_euler *euler, br_quat *quat); Description Functions to convert Euler angles to and from matrices and quaternions. Note that when the source transformation is a matrix, any non-rotational component of the transformation is lost. When converting to Euler angles, the order member in the appropriate br_euler must be set before the conversion is performed. Arguments The first argument points to the destination transformation and the second argument points to the source transformation. Return value Returns a pointer to the destination transformation. See also BrTransformToTransform ΓòÉΓòÉΓòÉ 7.6. 6.6 Quaternions ΓòÉΓòÉΓòÉ 6.6.1 Datatypes 6.6.1.1 br_quat Structure typedef struct br_quat { br_scalar x; br_scalar y; br_scalar z; br_scalar w; } br_quat; Description BRender's quaternion type. A unit quaternion, whose sum of squared elements is one, can be used to represent a rotation around an arbitrary vector. The X, Y and Z components of the quaternion hold the elements of this vector scaled to a length equal to sine of the angle of rotation. The w component holds the cosine of the angle. Associated macros BR_QUAT(x,y,z,w) Used for static initialisation of a quaternion. It will automatically convert its arguments to type br_scalar. Example br_quat quat=BR_QUAT(1/sqrt(3),1/sqrt(3),1/sqrt(3),0); 6.6.2 Functions 6.6.2.1 Quaternion conversion functions Syntax br_euler * BrQuatToEuler(br_euler *euler, br_quat *quat); br_matrix34 * BrQuatToMatrix34(br_matrix34 *mat, br_quat *quat); br_matrix4 * BrQuatToMatrix4(br_matrix4 *mat, br_quat *quat); br_quat * BrEulerToQuat(br_quat *quat, br_euler *euler); br_quat * BrMatrix34ToQuat(br_quat *quat, br_matrix34 *mat); br_quat * BrMatrix4ToQuat(br_quat *quat, br_matrix4 *mat); Description Functions to convert quaternions to and from matrices and Euler angles. Note that when the source transformation is a matrix, any non-rotational component of the transformation is lost. Arguments The first argument points to the destination transformation and the second argument points to the source transformation. Return value Returns a pointer to the destination transformation. See also BrTransformToTransform 6.6.2.2 BrQuatMul Syntax br_quat * BrQuatMul(br_quat *q, br_quat *l, br_quat *r); Description Multiply two quaternions together and place the result in a third destination quaternion. Quaternion multiplication has the effect of concatenating the individual transformations that each represents. It is not commutative. Arguments q A pointer to the destination quaternion. l,r Pointers to the two source quaternions. Return value Returns a pointer to the destination quaternion. See also BrQuatSlerp br_quat 6.6.2.3 BrQuatNormalise Syntax br_quat * BrQuatNormalise(br_quat *q, br_quat *qq); Description Normalise a quaternion. Rotations are represented as normalised quaternions in order to avoid unwanted scaling side-effects. If a large number of operations is performed on a quaternion, this functions should be used subsequently to ensure the resulting quaternion remains in normal form, and the sum of the squares of its elements is one. Arguments q A pointer to the normalised destination quaternion. qq A pointer to the source quaternion. Return value Returns a pointer to the normalised destination quaternion. See also br_quat BrQuatInvert 6.6.2.4 BrQuatInvert Syntax br_quat * BrQuatInvert(br_quat *q, br_quat *qq); Description Invert a quaternion and place the result in a second destination quaternion. The inverse of a quaternion represents the same rotation, but in reverse. Arguments q A pointer to the destination quaternion. qq A pointer to the source quaternion. Return value Returns a pointer to the destination quaternion. See also br_quat BrQuatNormalise 6.6.2.5 BrQuatSlerp Syntax br_quat * BrQuatSlerp(br_quat *q, br_quat *l, br_quat *r, br_scalar t, br_int_16 spins); Description The 'Slerp' operation (spherical linear interpolation) interpolates linearly between two quaternions along the most direct path between the two orientations. Moreover, extra spins (complete revolutions) can be inserted in the path. Arguments q A pointer to the normalised destination quaternion. l,r Pointers to the normalised quaternions to interpolate between. t Interpolation parameter in the range [0,1]. Zero corresponds to the source quaternion l, and one corresponds to the source quaternion r. spins Number of extra spins. A value of zero causes interpolation along the shortest path. A value of -1 causes interpolation along the longest path. Return value Returns a pointer to the normalised destination quaternion. See also BrQuatMul ΓòÉΓòÉΓòÉ 7.7. 6.7 Vectors ΓòÉΓòÉΓòÉ 6.7.1 Datatypes 6.7.1.1 br_vector# Structure typedef struct br_vector2 { br_scalar v[2]; } br_vector2; typedef struct br_vector3 { br_scalar v[3]; } br_vector3; typedef struct br_vector4 { br_scalar v[4]; } br_vector4; Description BRender's vector types. Associated macros BR_VECTOR2(a,b) BR_VECTOR3(a,b,c) BR_VECTOR4(a,b,c,d) These macros can be used for vector initialisation. Each argument is automatically converted to a scalar. Example br_vector3 va=BR_VECTOR3(0.0,1.0,2.0); 6.7.1.2 br_fvector# Structure typedef struct br_fvector2 { br_fraction v[2]; } br_fvector2; typedef struct br_fvector3 { br_fraction v[3]; } br_fvector3; typedef struct br_fvector4 { br_fraction v[4]; } br_fvector4; Description Brender's fractional vector types. They should be used in situations where each component will never exceed Γö╝1, for example, in the representation of surface normals. Associated macros BR_FVECTOR2(a,b) BR_FVECTOR3(a,b,c) BR_FVECTOR4(a,b,c,d) These macros can be used for vector initialisation. Each argument is automatically converted to a scalar. Example br_fvector2 vb=BR_FVECTOR2(0.1,-0.1); 6.7.2 Functions The vector functions are defined as macros. They are fast, and consequently perform very little range checking or similar argument validation. If constants are passed as arguments, they must be wrapped with the appropriate type conversion macros. 6.7.2.1 BrVector#Copy Syntax void BrVector2Copy(br_vector2 *v1, br_vector2 *v2); void BrVector3Copy(br_vector3 *v1, br_vector3 *v2); void BrVector4Copy(br_vector4 *v1, br_vector4 *v2); Description Copy a vector. Arguments v1 A pointer to the destination vector. v2 A pointer to the source vector. 6.7.2.2 BrVector#Set# Syntax void BrVector2Set(br_vector2 *v1, br_scalar s1, br _scalar s2); void BrVector3Set(br_vector3 *v1, br_scalar s1, br_scalar s2, br_scalar s3); void BrVector2SetInt(br_vector2 *v1, int i1, int i2); void BrVector3SetInt(br_vector3 *v1, int i1, int i2, int i3); void BrVector2SetFloat(br_vector2 *v1, float f1, float f2); void BrVector3SetFloat(br_vector3 *v1, float f1, float f2, float f3); Description Set a vector with scalar, integer or float arguments. Arguments v1 A pointer to the destination vector. s1,s2,s3 Scalar vector elements. i1,i2,i3 Integer vector elements. f1,f2,f3 Float vector elements. Example br_vector3 *va,*vb,*vc; ... BrVector3Set(va,BR_SCALAR(1.0),BR_SCALAR(-1.0),BR_SCALAR(2.0)); BrVector3SetInt(vb,1,2,3); BrVector3SetFloat(vc,PI,100,1/sqrt(2)); 6.7.2.3 BrVector#Negate Syntax void BrVector2Negate(br_vector2 *v1, br_vector2 *v2); void BrVector3Negate(br_vector3 *v1, br_vector3 *v2); Description Negate a vector and place the result in a second destination vector. Arguments v1 A pointer to the destination vector. v2 A pointer to the source vector. 6.7.2.4 BrVector#Add Syntax void BrVector2Add(br_vector2 *v1, br_vector2 *v2, br_vector2 *v3); void BrVector3Add(br_vector3 *v1, br_vector3 *v2, br_vector3 *v3); Description Add two vectors and place the result in a third destination vector. Symbolically: v1 = v2 + v3 Arguments v1 A pointer to the destination vector. v2,v3 Pointers to the source vectors. 6.7.2.5 BrVector#Accumulate Syntax void BrVector2Accumulate(br_vector2 *v1, br_vector2 *v2); void BrVector3Accumulate(br_vector3 *v1, br_vector3 *v2); Description Add one vector to another. Symbolically: v1 = v1 + v2 Arguments v1 A pointer to the accumulating vector. v2 A pointer to the vector to add. 6.7.2.6 BrVector#Sub Syntax void BrVector2Sub(br_vector2 *v1, br_vector2 *v2, br_vector2 *v3); void BrVector3Sub(br_vector3 *v1, br_vector3 *v2, br_vector3 *v3); Description Subtract one vector from another and place the result in a third destination vector. Symbolically: v1 = v2 - v3 Arguments v1 A pointer to the destination vector. v2,v3 Pointers to the source vectors. 6.7.2.7 BrVector#Scale Syntax void BrVector2Scale(br_vector2 *v1, br_vector2 *v2, br_scalar s); void BrVector3Scale(br_vector3 *v1, br_vector3 *v2, br_scalar s); Description Scale a vector by a scalar and place the result in a second destination vector. Arguments v1 A pointer to the destination vector. v2 A pointer to the source vector. s Scale factor. 6.7.2.8 BrVector#InvScale Syntax void BrVector2InvScale(br_vector2 *v1, br_vector2 *v2, br_scalar s); void BrVector3InvScale(br_vector3 *v1, br_vector3 *v2, br_scalar s); Description Scale a vector by the reciprocal of a scalar and place the result in a second destination vector. Arguments v1 A pointer to the destination vector. v2 A pointer to the source vector. s Reciprocal scale factor. 6.7.2.9 BrVector3Cross Syntax void BrVector3Cross(br_vector3 *v1, br_vector3 *v2, br_vector3 *v3); Description Calculate the cross product of two vectors and place the result in a third destination vector. Symbolically: v1 = v2 x v3 Arguments v1 A pointer to the destination vector. v2,v3 Pointers to the source vectors. 6.7.2.10 BrVector#Dot Syntax br_scalar BrVector2Dot(br_vector2 *v1, br_vector2 *v2); br_scalar BrVector3Dot(br_vector3 *v1, br_vector3 *v2); br_scalar BrVector4Dot(br_vector4 *v1, br_vector4 *v2); Description Calculate the dot product of two vectors. Arguments v1,v2 Pointers to the source vectors. Return value Returns the dot product of the two source vectors. 6.7.2.11 BrVector3Normalise# Syntax void BrVector3Normalise(br_vector3 *v1, br_vector3 *v2); void BrVector3NormaliseQuick(br_vector3 *v1, br_vector3 *v2); void BrVector3NormaliseLP(br_vector3 *v1, br_vector3 *v2); Description Normalise a vector and place the result in a second destination vector. BrVector3Normalise checks that the source vector is not of zero length. If it is, the unit vector along the X axis (1,0,0) is returned. BrVector3NormaliseQuick does not check for zero length. BrVector3NormaliseLP is a faster, low-precision version employing a reciprocal table and it does not check for zero length. Arguments v1 A pointer to the destination vector. v2 A pointer to the source vector. 6.7.2.12 BrVector#Length Syntax br_scalar BrVector2Length(br_vector2 *v1); br_scalar BrVector3Length(br_vector3 *v1); Description Calculate the length of a vector. Arguments v1 A pointer to the source vector. Return value Returns the length of the vector. See also BrVector#LengthSquared 6.7.2.13 BrVector#LengthSquared Syntax br_scalar BrVector2LengthSquared(br_vector2 *v1); br_scalar BrVector3LengthSquared(br_vector3 *v1); Description Calculate the squared length of a vector. Arguments v1 A pointer to the source vector. Return value Returns the squared length of the vector. See also BrVector#Length ΓòÉΓòÉΓòÉ 7.8. 6.8 Matrices ΓòÉΓòÉΓòÉ 6.8.1 Datatypes 6.8.1.1 br_matrix# Structure typedef struct br_matrix34 { br_scalar m[4][3]; } br_matrix34; typedef struct br_matrix4 { br_scalar m[4][4]; } br_matrix4; Description BRender's matrix types. 6.8.2 Functions 6.8.2.1 Matrix conversion functions Syntax br_euler * BrMatrix34ToEuler(br_euler *euler, br_matrix34 *mat); br_quat * BrMatrix34ToQuat(br_quat *quat, br_matrix34 *mat); br_matrix34 * BrEulerToMatrix34(br_matrix34 *mat, br_euler *euler); br_matrix34 * BrQuatToMatrix34(br_matrix34 *mat, br_quat *quat); br_euler * BrMatrix4ToEuler(br_euler *euler, br_matrix4 *mat); br_quat * BrMatrix4ToQuat(br_quat *quat, br_matrix4 *mat); br_matrix4 * BrEulerToMatrix4(br_matrix4 *mat, br_euler *euler); br_matrix4 * BrQuatToMatrix4(br_matrix4 *mat, br_quat *quat); Description Functions to convert matrices to and from quaternions and Euler angles. Note that when the source transformation is a matrix, any non-rotational component of the transformation is lost. Arguments The first argument points to the destination transformation and the second argument points to the source transformation. Return value Returns a pointer to the destination transformation. 6.8.2.2 BrMatrix#Copy# Syntax void BrMatrix34Copy(br_matrix34 *A, br_matrix34 *B); void BrMatrix4Copy34(br_matrix4 *A, br_matrix34 *B); void BrMatrix34Copy4(br_matrix34 *A, br_matrix4 *B); void BrMatrix4Copy(br_matrix4 *A, br_matrix4 *B); Description Copy a matrix. Transformations are preserved when copying between matrices of different size. Arguments A A pointer to the destination matrix. B A pointer to the source matrix. Example br_matrix34 mat1,mat2; ... BrMatrix34Copy(&mat1,&mat2); 6.8.2.3 BrMatrix#Mul Syntax void BrMatrix34Mul(br_matrix34 *A, br_matrix34 *B, br_matrix34 *C); void BrMatrix4Mul(br_matrix4 *A, br_matrix4 *B, br_matrix4 *C); Description Multiply two matrices together and place the result in a third matrix. Symbolically: A = B C Arguments A A pointer to the destination matrix. B,C Pointers to the source matrices. See also BrMatrix#Pre# BrMatrix34Post 6.8.2.4 BrMatrix#Pre# Syntax void BrMatrix34Pre(br_matrix34 *A, br_matrix34 *B); void BrMatrix4Pre34(br_matrix4 *A, br_matrix34 *B); Description Pre-multiply one matrix by another. Symbolically: A = B A Arguments A A pointer to the source/destination matrix. B A pointer to the pre-multiplying matrix. See also BrMatrix34Post BrMatrix34Mul 6.8.2.5 BrMatrix34Post Syntax void BrMatrix34Post(br_matrix34 *A ,br_matrix34 *B); Description Post-multiply one matrix by another. Symbolically: A = A B Arguments A A pointer to the source/destination matrix. B A pointer to the post-multiplying matrix. See also BrMatrix#Pre# BrMatrix34Mul 6.8.2.6 BrMatrix#Identity Syntax void BrMatrix34Identity(br_matrix34 *mat); void BrMatrix4Identity(br_matrix4 *mat); Description Generate the identity transformation matrix. Arguments mat A pointer to the destination matrix. See also BrMatrix34Rotate BrMatrix34Scale BrMatrix34Translate 6.8.2.7 BrMatrix34#Rotate Syntax void BrMatrix34Rotate(br_matrix34 *mat, br_angle r, br_vector3 *axis); void BrMatrix34PreRotate(br_matrix34 *mat, br_angle r, br_vector3 *axis); void BrMatrix34PostRotate(br_matrix34 *mat, br_angle r, br_vector3 *axis); Description Generate, pre-multiply by or post-multiply by a matrix representing a general rotation about a given axis through a given angle. Arguments mat A pointer to the source/destination matrix. axis A pointer to the normalised vector giving the axis about which rotation will occur. r Rotation angle. See also br_quat BrMatrix34Rotate# 6.8.2.8 BrMatrix34Rotate# Syntax void BrMatrix34RotateX(br_matrix34 *mat, angle rx); void BrMatrix34RotateY(br_matrix34 *mat, angle ry); void BrMatrix34RotateZ(br_matrix34 *mat, angle rz); Description Generate a matrix representing a rotation about the X, Y or Z coordinate axis. Arguments mat A pointer to the destination matrix. rx,ry,rz Rotation angles around each coordinate axis. See also BrMatrix34#Rotate 6.8.2.9 BrMatrix34PreRotate# Syntax void BrMatrix34PreRotateX(br_matrix34 *mat, angle rx); void BrMatrix34PreRotateY(br_matrix34 *mat, angle ry); void BrMatrix34PreRotateZ(br_matrix34 *mat, angle rz); Description Pre-multiply a matrix by a matrix representing a rotation about the X, Y or Z coordinate axis. Arguments mat A pointer to the source/destination matrix. rx,ry,rz Rotation angles around each coordinate axis. Example br_angle angle_z=BR_ANGLE_RAD(PI/2); br_matrix34 mat; ... BrMatrix34PreRotateZ(&mat,angle_z); See also BrMatrix34#Rotate 6.8.2.10 BrMatrix34PostRotate# Syntax void BrMatrix34PostRotateX(br_matrix34 *mat, angle rx); void BrMatrix34PostRotateY(br_matrix34 *mat, angle ry); void BrMatrix34PostRotateZ(br_matrix34 *mat, angle rz); Description Post-multiply a matrix by a matrix representing a rotation about the X, Y or Z coordinate axis. Arguments mat A pointer to the source/destination matrix. rx,ry,rz Rotation angles around each coordinate axis. Example br_angle angle_x=BR_ANGLE_DEG(90.0); br_matrix34 mat; ... BrMatrix34PostRotateX(&mat,angle_x); See also BrMatrix34#Rotate 6.8.2.11 BrMatrix34Translate Syntax void BrMatrix34Translate(br_matrix34 *mat, br_scalar x, br_scalar y, br_scalar z); Description Generate a translation transformation matrix. Arguments mat A pointer to the destination matrix. x,y,z Translation along each coordinate axis. See also BrMatrix34PreTranslate BrMatrix34PostTranslate 6.8.2.12 BrMatrix34PreTranslate Syntax void BrMatrix34PreTranslate(br_matrix34 *mat, br_scalar x, br_scalar y, br_scalar z); Description Pre-multiply a matrix by a matrix representing a translation. Arguments mat A pointer to the source/destination matrix. x,y,z Translation along each coordinate axis. See also BrMatrix34Translate BrMatrix34PostTranslate 6.8.2.13 BrMatrix34PostTranslate Syntax void BrMatrix34PostTranslate(br_matrix34 *mat, br_scalar x, br_scalar y, br_scalar z); Description Post-multiply a matrix by a matrix representing a translation. Arguments mat A pointer to the source/destination matrix. x,y,z Translation along each coordinate axis. See also BrMatrix34Translate BrMatrix34PreTranslate 6.8.2.14 BrMatrix#Scale Syntax void BrMatrix34Scale(br_matrix34 *mat, br_scalar sx, br_scalar sy, br_scalar sz); void BrMatrix4Scale(br_matrix4 *mat, br_scalar sx , br_scalar sy, br_scalar sz); Description Generate a scaling transformation matrix. Arguments mat A pointer to the destination matrix. sx,sy,sz Scaling factors along each coordinate axis. See also BrMatrix34PreScale BrMatrix34PostScale 6.8.2.15 BrMatrix34PreScale Syntax void BrMatrix34PreScale(br_matrix34 *mat, br_ scalar sx, br_scalar sy, br_scalar sz); Description Pre-multiply a matrix by a matrix representing a scaling transformation. Arguments mat A pointer to the source/destination matrix. sx,sy,sz Scaling factors along each coordinate axis. See also BrMatrix34PostScale BrMatrix#Scale 6.8.2.16 BrMatrix34PostScale Syntax void BrMatrix34PostScale(br_matrix34 *mat, br_ scalar sx, br_scalar sy, br_scalar sz); Description Post-multiply a matrix by a matrix representing a scaling transformation. Arguments mat A pointer to the source/destination matrix. sx,sy,sz Scaling factors along each coordinate axis. See also BrMatrix#Scale BrMatrix34PreScale 6.8.2.17 BrMatrix34Shear# Syntax void BrMatrix34ShearX(br_matrix34 *mat, br_scalar sy, br_scalar sz); void BrMatrix34ShearY(br_matrix34 *mat, br_scalar sx, br_scalar sz); void BrMatrix34ShearZ(br_matrix34 *mat, br_scalar sx, br_scalar sy); Description Generate a shear transformation, invariant along the X, Y or Z axis. Arguments mat A pointer to the destination matrix. sx,sy,sz Shear factors along each coordinate axis. See also BrMatrix34PreShear# BrMatrixPostShear# 6.8.2.18 BrMatrix34PreShear# Syntax void BrMatrix34PreShearX(br_matrix34 *mat, br_scalar sy, br_scalar sz); void BrMatrix34PreShearY(br_matrix34 *mat, br_scalar sx, br_scalar sz); void BrMatrix34PreShearZ(br_matrix34 *mat, br_scalar sx, br_scalar sy); Description Pre-multiply a matrix by a matrix representing a shear transformation invariant along the X, Y or Z coordinate axis. Arguments mat A pointer to the source/destination matrix. sx,sy,sz Shear factors along each coordinate axis. See also BrMatrix34Shear# BrMatrix34PostShear# 6.8.2.19 BrMatrix34PostShear# Syntax void BrMatrix34PostShearX(br_matrix34 *mat, br_scalar sy, br_scalar sz); void BrMatrix34PostShearY(br_matrix34 *mat, br_scalar sx, br_scalar sz); void BrMatrix34PostShearZ(br_matrix34 *mat, br_scalar sx, br_scalar sy); Description Post-multiply a matrix by a matrix representing a shear transformation invariant along the X, Y or Z coordinate axis. Arguments mat A pointer to the source/destination matrix. sx,sy,sz Shear factors along each coordinate axis. See also BrMatrix34Shear# BrMatrix34PreShear# 6.8.2.20 BrMatrix#Apply# Syntax void BrMatrix34ApplyV(br_vector3 *a, br_vector3 *b, br_matrix34 *C); void BrMatrix34ApplyP(br_vector3 *a, br_vector3 *b, br_matrix34 *C); void BrMatrix34Apply (br_vector3 *a, br_vector4 *b, br_matrix34 *C); void BrMatrix4ApplyV(br_vector4 *a, br_vector3 *b, br_matrix4 *C); void BrMatrix4ApplyP(br_vector4 *a, br_vector3 *b, br_matrix4 *C); void BrMatrix4Apply (br_vector4 *a, br_vector4 *b, br_matrix4 *C); Description Takes a br_vector3, a point or a br_vector4, and applies a matrix to it. Symbolically: a = b C Arguments a A pointer to the destination vector. b A pointer to the source vector. C A pointer to the source matrix. See also BrMatrix#Mul BrMatrix#TApply# 6.8.2.21 BrMatrix#TApply# Syntax void BrMatrix34TApplyV(br_vector3 *a, br_vector3 *b, br_matrix34 *C); void BrMatrix34TApplyP(br_vector3 *a, br_vector3 *b, br_matrix34 *C); void BrMatrix34TApply (br_vector4 *a, br_vector4 *b, br_matrix34 *C); void BrMatrix4TApplyV(br_vector4 *a, br_vector3 *b, br_matrix4 *C); void BrMatrix4TApplyP(br_vector4 *a, br_vector3 *b, br_matrix4 *C); void BrMatrix4TApply (br_vector4 *a, br_vector4 *b, br_matrix4 *C); Description As for BrMatrix#Apply# , but the transpose of the matrix is applied. Arguments a A pointer to the destination vector. b A pointer to the source vector. C A pointer to the source matrix. See also BrMatrix#Mul BrMatrix#Apply# 6.8.2.22 BrMatrix4Perspective Syntax void BrMatrix4Perspective(br_matrix4 *mat, br_angle field_of_view, br_scalar aspect, br_scalar hither, br_scalar yon); Description This function generates the transformation matrix which BRender uses to map a scene from world space into camera space. The transformation takes the entire view volume (a prism of a given angle, with front and back limits hither and yon) and maps it into the rendering volume, a half cube delimited by the coordinates (-1,-1,0) and (1,1,-1). Arguments mat A pointer to the destination matrix. field_of_view The angle subtended between the sides of the view volume. aspect The ratio of the sides of the view volume. hither, yon The position of the front and back of the view volume, measured from the camera. Example br_matrix4 mat; br_angle fov=BR_ANGLE_DEG(45.0); br_scalar aspect=BR_SCALAR(1.46); ... BrMatrix4Perspective(&mat,fov,aspect,BR_SCALAR(1.0),BR_SCALAR(20.0)); See also br_camera 6.8.2.23 BrMatrix4Determinant Syntax br_scalar BrMatrix4Determinant(br_matrix4 *mat); Description Calculate the determinant of a matrix. Arguments mat A pointer to the source matrix. Return value If the inverse of the matrix exists, the determinant is returned. If th ere is no inverse, scalar zero is returned. See also BrMatrix4Adjoint BrMatrix#Inverse 6.8.2.24 BrMatrix4Adjoint Syntax void BrMatrix4Adjoint(br_matrix4 *A, br_matrix4 *B); Description Find the adjoint of a matrix (the transposed matrix of co-factors). Arguments A A pointer to the destination adjoint matrix. B A pointer to the source matrix. See also BrMatrix4Determinant BrMatrix#Inverse 6.8.2.25 BrMatrix#Inverse Syntax br_scalar BrMatrix34Inverse(br_matrix34 *out, br_matrix34 *in); br_scalar BrMatrix4Inverse(br_matrix4 *out, br_matrix4 *in); Description Find the inverse of a matrix. Arguments *out A pointer to the inverted destination matrix. *in A pointer to the source matrix. Return value If the inverse exists, the determinant of the source matrix is returned . If there is no inverse, scalar zero is returned. Example br_matrix34 mat,inv; ... BrMatrix34Inverse(&inv,&mat); See also BrMatrix4Determinant BrMatrix4Adjoint BrMatrix34LPInverse 6.8.2.26 BrMatrix34LPInverse Syntax void BrMatrix34LPInverse(br_matrix34 *A, br_matrix34 *B); Description Find the inverse of a length-preserving transformation matrix. Arguments A A pointer to the inverted destination matrix. B A pointer to the source matrix. See also BrMatrix#Inverse BrMatrix34LPNormalise 6.8.2.27 BrMatrix34LPNormalise Syntax void BrMatrix34LPNormalise(br_matrix34 *A, br_matrix34 *B); Description 'Normalise' a matrix. This function takes a matrix and adjusts it so that it represents a length-preserving transformation. For example, it can be applied to a length-preserving matrix which has undergone a long sequence of operations, to ensure that the final result is still truly length-preserving. Arguments A A pointer to the normalised destination matrix. B A pointer to the source matrix. See also BrMatrix34LPInverse 6.8.2.28 BrMatrix34RollingBall Syntax void BrMatrix34RollingBall(br_matrix34 *mat, br_int_16 dx, br_int_16 dy, br_int_16 radius); Description This function generates a matrix which provides an intuitive way of controlling the rotation of 3D objects with a mouse or other 2D pointing device. Imagine a ball on a flat surface, with a mobile flat surface resting on top of the ball. As the top surface moves about, the ball rotates. Arguments mat A pointer to the destination matrix. dx,dy The amount the 'top surface' has moved in each direction. radius The radius of the imaginary ball. Example br_int_16 mouse_x,mouse_y; br_matrix34 mat; ... BrMatrix34RollingBall(&mat,-mouse_x,mouse_y,500); 6.8.2.29 Transformation conversion functions Syntax void BrTransformToMatrix34(br_matrix34 *mat, br_transform *xform); void BrMatrix34ToTransform(br_transform *xform, br_matrix34 *mat); Description Functions to convert between matrices and the generic transformation type br_transform. Arguments mat A pointer to a matrix. xform A pointer to a generic transformation. The first argument points to the destination transformation and the second argument points to the source transformation. See also BrMatrix#Transform BrTransformToTransform 6.8.2.30 BrMatrix#Transform Syntax void BrMatrix34PreTransform(br_matrix34 *mat, br_transform *xform); void BrMatrix34PostTransform(br_matrix34 *mat, br_transform *xform); void BrMatrix4PreTransform(br_matrix4 *mat, br_transform *xform); Description Pre-multiply or post-multiply a matrix by a matrix representing a generic transformation. Arguments mat A pointer to the source/destination matrix. xform A pointer to a generic transformation. See also BrTransformToTransform 7.1 Appendix A - DOSGfx - Overview DOSGfx is a small set of screen handling functions intended for DOS based BRender applications. The functions simplify initialisation of colour buffers, palettes and video display hardware. The BRENDER_DOS_GFX environment variable can be used to set the default graphics mode and resolution. It has the following format: VESA|MCGA,[W:<width>],[H:<height>],[B:<bits/pixel>],[M:<mode number>] If the environment variable specifies an unavailable mode or resolution, DOSGfx will fail to initialise and return an error message. 7.1.2 Functions 7.1.2.1 DOSGfxBegin Syntax br_pixelmap * DOSGfxBegin(char *setup_string); Description Create a pixelmap which represents the graphics hardware screen. Subsequently, the BrPixelmapMatch function can be used to create a second screen, and the BrPixelmapDoubleBuffer function can be used to swap between them. Arguments *setup_string An options string, given in the following format: VESA|MCGA,[W:<width>],[H:<height>],[B:<bits/pixel>],[M:<mode number>] The default string 'MCGA,W:320,H:200,B:8' is used if NULL is passed and the BRENDER_DOS_GFX environment variable has not been set. If the environment variable has been set, any options given here that differ will be used instead. Return value Returns a pointer to a pixelmap representing the graphics hardware screen. 7.1.2.2 DOSGfxEnd Syntax void DOSGfxEnd(void); Description Close down DOSGfx. 7.1.2.3 DOSGfxPaletteSet Syntax void DOSGfxPaletteSet(br_pixelmap *pm); Description Set the VGA/VESA hardware palette with the contents of a given pixelmap. Arguments pm A pointer to a 1x256 BR_PMT_RGBX_888 pixelmap containing the palette. 7.1.2.4 DOSGfxPaletteSetEntry Syntax void DOSGfxPaletteSetEntry(int I, br_colour colour); Description Set a single colour in the VGA/VESA hardware palette. Arguments I Colour number. colour New colour. 7.2 Appendix B - The GEOCONV tool GEOCONV is a command-line tool which converts models from one geometry format to another, allowing models generated with 3D modelling packages to be used within BRender. Usage: geoconv {options} The options are treated as commands executed in left-to-right order: <input-file> Load a file into current data -I <input-type> Set input file type -o <file> Generate output file from current data -O <output-type> Set type of data to generate -n Normalise models to radius of 1.0 -c Centre models on 0,0,0 -f Flip face normals -w Fix wrapped texture coordinates -F <flag> Set or clear a model flag -p Remove identical vertices -P < float> Merge vertices within a given tolerance -C Remove degenerate faces, unused vertices and duplicate faces -m Collapse current data to one actor and one model -r <pattern> Restrict subsequent operations to things matching <pattern> -l List current data -g Set each model to a different smoothing group -S <sort-type> Set sorting on output -N <material-name> Set all models to use named material -M <map-type>,<axis>,<axis> Apply a default U,V mapping to models -s <float> Uniform scale applied to models -s <float>,<float>,<float> Non-uniform scale applied to models -t <float>,<float>,<float> Translation applied to models -a <axis>,<axis>,<axis> Remap axes -D <name> Rename models -L <name> Rename materials <input-type> = dat BRender model files nff Eric Haines' Neutral File Format asc 3D Studio .ASC file If a type is not specified, it will be guessed from the extension of the filename. <output-type> = models (.dat or .brm ) c-models Source code for model data structures <axis> = x y z positive input axes +x +y +z positive input axes -x -y -z negative input axes <map-type> = none disc plane cylinder sphere <material-name> = <string> default <sort-type> = none name <flag> = +d Set BR_MODF_DONT_WELD -d Clear BR_MODF_DONT_WELD +o Set BR_MODF_KEEP_ORIGNAL -o Clear BR_MODF_KEEP_ORIGNAL +t Set BR_MODF_GENERATE_TAGS -t Clear BR_MODF_GENERATE_TAGS +q Set BR_MODF_QUICK_UPDATE -q Clear BR_MODF_QUICK_UPDATE There are three related points worth noting: 3D Studio saves models with their longest axis down Z, and may need to be re-oriented with the remap axis option (-a). For the sake of consistency, it is advisable to pre-scale models as necessary with this tool, rather than scale them within a BRender application. By default, if there are many models in a source file, they will be separated into individual models (but saved as a single file). 7.3 Appendix C - The TEXCONV tool This is a command-line tool which provides texture import, scaling, quantizing and remapping functions. Usage: texconv {options} Texconv options are treated as commands, performed in left-to-right order: <input-file> Load a file into current data -I <input-type> Set input file type -O <output-type> Set output file type -a Toggle current 32 bit pixelmaps to exclude/include alpha data (default exclude) -c <pixelmap-type>[,t] Convert to pixelmap type, may involve quantizing. 't' is the alpha channel threshold (0-255) for conversions involving 32 bit pixelmaps. -f 'Forget' all current data -n <name> Assign identifier 'name' to data -o <file> Generate output file from current data -r <file>,<pixelmap-type>, offset,x,y[,P] Load raw data file as pixelmap-type, with pixel dimensions x,y, from offset into file. P is specified to load as a palette -v View snapshot of current data (only BR_PMT_INDEX_8) -P <name>[,RAW] Apply palette from a file to all current indexed pixelmaps. If RAW is specified, the palette file is 768 byte RGB, otherwise pixelmap format -Q <name>[,b,r] Quantize to palette supplied (pixelmap format) using (b)ase and (r)ange palette entries -R b,r Quantize and remap to (b)ase,(r)ange colours (both values in the range 0 to 255) -S x,y[,<float>] Scale to new x,y dimensions using optional filter size (default 3.0) @file Perform all operation contained within <file> <input-type> = pix BRender Pixelmap format bmp Windows BMP format (4, 8, 24, RLE4, RLE8) gif CompuServ GIF format (1 to 8 bit) tga Targa TGA format (8, 15, 16, 24, 32 bit) iff Amiga IFF/LBM format (1 to 8 bit) If a type is not specified, it will be guessed from the extension of the filename. <output-type> = palette Palette information stripped from bitmap (.pix) image Pixelmap without palette (.pix) pixelmap Image with any palette information (.pix) If a type is not specified, the default is pixelmap <pixelmap-type> = BR_PMT_INDEX_8 (8 bit indexed) BR_PMT_RGB_555 (RGB 16 bit 5 bits per colour) BR_PMT_RGB_565 (RGB 16 bit 5, 6, 5 bits per colour) BR_PMT_RGB_888 (RGB 24 bit 8 bits per pixel) BR_PMT_RGBX_888 (RGB 32 bit 8 bits per pixel) BR_PMT_RGBA_8888 (RGBA 32 bit 8 bits per component) 7.4 Appendix D - The MKSHADES tool MKSHADES is a command-line tool which takes a source palette (usually a 1 by n BR_PMT_RGBX_888 pixelmap generated by TEXCONV), and generates an indexed shade table. The shade table is used when rendering into an 8 bit indexed pixelmap, to perform shading across a lit textured material. Normally, the range of the shade table corresponds to the current hardware palette and the indices in the texture itself. Usage: mkshades (options) <pallete> Source BRender palette -o <shade-table> Output shade table pixelmap [-d <dest-palette>] Destination BRender palette if different from source [-n <num_shades>] Number of shades to generate (default 64) [-r <base>,<size>] Range of colours in output palette (default 0, 256)