br_material
typedef
material.h
for precise declaration and ordering)
br_uint_32 flags Flags determining how this material is rendered
br_ufraction ka The ambient lighting contribution
br_ufraction kd The directional lighting contribution
br_ufraction ks The specular lighting contribution
br_scalar power Specular power - the `spread' of a specular highlight
br_colour colour Material colour, when rendering in `true' colour
br_uint_8 index_base The unlit index (or row of a shade table)
br_uint_8 index_range The range to the fully lit index (or row of a shade table)
br_pixelmap * index_shade A shade table (for indexed textures only)
br_pixelmap * index_blend A blend table (for indexed textures only)
br_pixelmap * colour_map An optional pixel map based texture
br_matrix23 map_transform Transform to apply to texture map
char * identifier Material name
void * user User data (application dependent)
BrEnvironmentSet()
85
, BrModelApplyMap()
231
, BrModelFitMap()
233
.
BrZbModelRender()
249
.
br_actor
74
, br_model
228
, br_face
122
, br_vertex
367
.
br_renderbounds_cbfn
307
, br_model_custom_cbfn
247
.
The effects of various combinations of the first three flags are not particularly obvious so are described in the following table. The Texture column indicates whether the material is effectively textured. The Colour column indicates whether the pixel map rendered to is indexed or `true' colour (it is assumed that any texture shares this property). The `Pixels Set To' column describes how each pixel of a face using the material is set. Note that `texel' is the term used to refer to the element of the texture map corresponding to a particular screen pixel.
Table showing effects of different combinations of material lighting flags
The following formula*1 shows how the lighting l of a face depends upon q, the angle at the face between the light source and the face normal, and f, the angle at the face between the viewer and the reflected light ray. Note that with high k values it is apparently possible for l to be as large as 3, however l is clamped to the range [0,1).
The other four variables in the equation are listed respectively, below.
Zero can produce a material whose illumination is highly dependent upon light sources, whereas higher values can give ever fluorescent or luminous effects.
A typical sunny scene might have most materials with a significant ambient contribution, whereas a dusk scene might have a much lower one, and a moonlit one, probably zero.
Zero can give a shiny surface, whereas higher values can give surfaces a more matt appearance.
The greater the value, the more visible highlights will be.
The greater the value, the sharper any highlights will be. A typical value is 20.
This member only applies to materials without textures - with textures, this member is ignored.
This member only applies to materials without textures - with textures, this member is ignored.
Thus an 8 bit indexed colour texture map requires a shade table with 256 columns and two or more rows (one being redundant). A selection of shade table types for use with 8 bit textures are described below.
The shade table converts 8 bit texels into 8 bit lit pixel values, by using the pixel in the shade table at the column given by the texel and the row given by the monochrome lighting level.
The shade table converts 8 bit texels into 15 bit lit pixel values, by using the pixel in the shade table at the column given by the texel and the row given by the monochrome lighting level.
The shade table converts 8 bit texels into 8 bit lit pixel values, by using a single 256 column wide table, but with 24 bit colour values in order that true colour lighting can be applied. The red and green components of each value are actually column indices used to obtain a blue component which is produced as the output pixel. The table is thus read three times.
Thus an 8 bit indexed colour texture map blend table needs 256 columns and 256 rows. The blend table is only used if
Given that the blend table tabulates an output for every possible pair of input pixels, any function can be represented, e.g. exclusive-or, inverse, inclusive-or, mask, average, etc.
The blend table is typically used for translucence effects, e.g. ghosts, flames, frosted glass, etc.
Note that in the case of the depth buffer renderer, while the output pixel will only be written if it is nearer than the existing pixel, it will never modify the depth buffer value. This is because it is assumed to be an intangible surface. Therefore, it may be necessary to render such materials in a separate stage.
Note that if both a blend table and shade table is used (the material has an indexed texture which is lit and blended), the shade table is applied first, followed by the blend table.
Blend tables, as with shade tables, also need to be added to the registry before use.
Pixels that are zero in the pixel map are not further processed for colour information, and are effectively transparent. A face is not rendered where such pixels appear on its surface, nor are any corresponding values written to any depth buffer. Note though, that a 2D pick function will still pick a transparent face. For more sophisticated transparency effects see the description of
Note that indexed colour textures must also have a corresponding shade table.
Members
Behaviour
This member determines how faces using the material are rendered, in terms of other members and aspects of the scene.br_uint_32 flags
Lighting
When a material is lit (BR_MATF_LIGHT
is set, but not BR_MATF_PRELIT
) a lighting calculation is performed to calculate the light reaching the viewer. This will depend upon the face's orientation with respect to the viewer and the light sources.
The ambient lighting contribution for lit materials. This is the amount of light assumed to be reflected from other objects and lighting in general, i.e. not from light actors. This means that even in a scene with all lights disabled, a lit material will still be visible if it has a non-zero ambient lighting contribution.br_ufraction ka
The diffuse lighting contribution for lit materials. This determines how much of the reflected light is made up of the component dependent upon the angle of the face to the direction of the light illuminating it. The closer the face comes to being perpendicular to the light source, the more light the face receives, and thus the more diffuse light that can be reflected.br_ufraction kd
The specular lighting contribution for this lit materials. This determines how much reflected light is made up of the component dependent upon the angle between the reflected light source and the direction of viewer (naturally, if the angle is zero, the component will be at its maximum).br_ufraction ks
This member applies a power to the specular lighting contribution.br_scalar power
Colour
When rendering in `true' colour, the value of this member is taken as the basic colour of the face, which may of course be affected by lighting (if br_colour colour
BR_MATF_LIGHT
is set, but not BR_MATF_PRELIT
).
When rendering in indexed colour, this member determines the lower value of the index range used to colour a face. When lit, the light level is factored with br_uint_8 index_base
index_range
to obtain an index between index_base
and index_base
+
index_range
-1
. Without lighting, index_base
is used to set every pixel of the face.
When rendering in indexed colour, this member determines the number of index values that can be selected with a given lighting level, starting at br_uint_8 index_range
index_base
.
Materials with indexed colour texture maps can only be lit if they are accompanied by an appropriate shade table. The shade table is simply a way of tabulating the output pixel given a particular texel and a particular lighting level. The texel generally indexes the column and the lighting level, the row. The shade table must therefore have the full complement of columns necessary for the pixel size of the texture map. The shade table may have any number of rows, as the lighting level directly selects the row.br_pixelmap * index_shade
BR_PMT_INDEX_8 shade table to BR_PMT_INDEX_8 output
BR_PMT_RGB_555 shade table to BR_PMT_RGB_555 output
BR_PMT_RGBX_888 shade table to BR_PMT_INDEX_8 output
Blending is a way of making the destination pixel depend upon the existing contents of the output buffer. The blend table like the shade table tabulates the output pixel given a particular texel and the pixel already in the output buffer. The texel indexes the column and the existing output pixel the row. The shade table must therefore have the full complement of rows as well as columns necessary for the pixel size of the texture map.br_pixelmap * index_blend
BR_MATF_BLEND
is set, and if set this member should not be Null
. Texture
A pointer to a pixel map containing a pattern with which to cover faces using this material.br_pixelmap * colour_map
index_blend
above.
The transform to apply to texture co-ordinates. This enables textures to be rotated, scaled, sheared, and translated. Moreover, this transform can be continuously modified, thus providing animated texture effects. for details of how texture maps can be applied to a model's faces.br_matrix23 map_transform
Supplementary
Pointer to unique, zero terminated, character string (or char * identifier
Null
if not required). Can be used as a handle to retrieve a pointer to the material. Not intended for intensive use. Typically used to collect pointers to materials loaded using BrMaterialLoad()
165 and added to the registry using
BrMaterialAdd()
158. Also ideal for diagnostic purposes.
A non-unique string can be supplied, but which of a set of materials having the same string will be matched by search functions (See BrMaterialFind()
162), is undefined. Also in consideration of searching, it is not recommended that non-alphabetic characters are used, especially Slash (`/'), Asterisk (`*'), and Query (`?'), which are used for pattern matching.
This member can be modified by the programmer at any time.
If identifier
is set by BrMaterialLoad()
165 or
BrMaterialLoadMany()
165
it will have been constructed using BrResStrDup()
55.
void* user
Null
upon allocation, and not accessed by BRender thereafter.
Copy/Assign
The br_material
151 structure should not be copied directly, e.g. by structure assignment. If a similar material is required, a new one should be allocated and pertinent members copied individually. Care may be needed in copying
identifier
.
Materials that have been added to the registry may be accessed by BRender during rendering.
If any changes are made to materials involved in rendering, they must be updated before the next rendering in which they are involved.
A pointer to a material.
Returns a pointer to the added item, else
Access & Maintenance
Materials must be added to the registry if they are involved in rendering a scene. They should not be modified during rendering.
Description:
Add a material to the registry, updating it as necessary. All materials must be added to the registry before they are subsequently involved in rendering.BrMaterialAdd()
br_material* BrMaterialAdd(br_material* material)
br_material * material
br_material *
Null
if unsuccessful.BrMaterialUpdate()
159,
BrMaterialAddMany()
158BrMaterialLoad()
165,
BrMaterialFind()
162,
BrMaterialRemove()
159.
A pointer to an array of pointers to materials.
Number of materials to add to the registry.
Returns the number of materials added successfully.
Description:
Add a number of materials to the registry, updating them as necessary.BrMaterialAddMany()
br_uint_32 BrMaterialAddMany(br_material* const* materials, int n)
br_material * const * materials
int n
br_uint_32
BrMaterialUpdate()
159,
BrMaterialAdd()
158,
BrMaterialRemove()
159,
BrMaterialRemoveMany()
159
Description:
Update a material that has changed in some respect since the previous update of this material (or BrMaterialUpdate()
BrMaterialAdd()
158).
Declaration:
void BrMaterialUpdate(br_material* material, br_uint_16 flags)
Arguments:
br_material * material
A pointer to a material.
br_uint_16 flags
Item update flags. In general, BR_MATU_ALL
should be used. However, the following table describes when to use more specific update flags. Note that flags can be combined using the `Or' operation (BR_MATU_ALL
is such a combination of the other flags, for your convenience).
See Also:
BrMaterialAdd()
158
.
A pointer to a material.
Returns a pointer to the item removed.
Description:
Remove a material from the registry.BrMaterialRemove()
br_material* BrMaterialRemove(br_material* material)
br_material * material
br_material *
BrMaterialAdd()
158
A pointer to an array of pointers materials.
Number of materials to remove from the registry.
Returns the number of items removed successfully.
Description:
Remove a number of materials from the registry.BrMaterialRemoveMany()
br_uint_32 BrMaterialRemoveMany(br_material* const* materials, int n)
br_material * materials
int n
br_uint_32
BrMaterialAddMany()
158
Initialisation
The material is automatically initialised to zero by BrMaterialAllocate()
160. Members should then be set appropriately. Re-initialisation is not recommended - destroy and reconstruct.
Construction & Destruction
Apart from import and platform specific functions, materials should only be constructed by the following BRender function. Destruction should naturally be performed by the corresponding `free' function, usually BrMaterialFree()
161. Note that a material should be removed from the registry before being destroyed.
String to initialise the
Returns a pointer to the new material, or
A pointer to a material.
Search pattern.
Returns the number of items matching the search pattern.
Description:
Allocate a new material.BrMaterialAllocate()
br_material* BrMaterialAllocate(const char* name)
const char * name
identifier
member to.br_material *
Null
if unsuccessful.
Description:
Deallocate a material and any associated memory.BrMaterialFree()
void BrMaterialFree(br_material* m)
br_material * m
Supplementary
Description:
Count the number of registered materials whose names match a given search pattern. The search pattern can include the standard wild cards `*' and `?'.BrMaterialCount()
br_uint_32 BrMaterialCount(const char* pattern)
const char * pattern
br_uint_32
BrMaterialEnum()
161,
BrMaterialFind()
162
Description:
Calls a call-back function for every material in the registry matching a given search pattern. The call-back is passed a pointer to each matching material, and its second argument is an optional pointer supplied by the user. The search pattern can include the standard wild cards `*' and `?'. The call-back itself returns a BrMaterialEnum()
br_uint_32
348 value. The enumeration will halt at any stage if the return value is non-zero.
Declaration:
br_uint_32 BrMaterialEnum(const char* pattern, br_material_enum_cbfn* callback, void* arg)
Arguments:
const char * pattern
Search pattern.
br_material_enum_cbfn * callback
A pointer to a call-back function.
void * arg
An optional argument to pass to the call-back function.
Result:
br_uint_32
Returns the first non-zero call-back return value, or zero if all matching items are enumerated.
Example:
br_uint_32 BR_CALLBACK test_callback(br_material* material, void* arg) { br_uint_32 count; ... return(count); } ... { br_uint_32 enum; ... enum = BrMaterialEnum("material",&test_callback,NULL); }
BrMaterialFind()
Declaration:
br_material* BrMaterialFind(const char* pattern)
Arguments:
const char * pattern
Search pattern.
Result:
br_material *
Returns a pointer to the material if found, otherwise Null
. If a call-back exists and is called, the call-back's return value is returned.
See Also:
BrMaterialFindHook()
163
, BrMaterialFindMany()
162
Search pattern.
A pointer to an array of pointers to materials.
Maximum number of materials to find.
Returns the number of materials found. The pointer array is filled with pointers to the found materials.
Description:
Find a number of materials in the registry by name. The search pattern can include the standard wild cards `*' and `?'.BrMaterialFindMany()
br_uint_32 BrMaterialFindMany(const char* pattern, br_material** materials, int max)
const char * pattern
br_material ** materials
int max
br_uint_32
BrMaterialFind()
162,
BrMaterialFindHook()
163
A pointer to a call-back function.
Description:
Functions to set up a call-back.BrMaterialFindHook()
br_material_find_cbfn* BrMaterialFindHook(br_material_find_cbfn* hook)
br_material_find_cbfn * hook
BrMaterialFind()
162 is unsuccessful and a call-back has been set up, the call-back is passed the search pattern as its only argument. The call-back should then return a pointer to a substitute or default item.
For example, a call-back could be set up to return a default material if the desired material cannot be found in the registry.
The function BrMaterialFindFailedLoad()
164
is provided and will probably be sufficient in many cases.
Result:
br_material_find_cbfn *
Returns a pointer to the old call-back function.
Example:
br_material BR_CALLBACK * test_callback(const char* pattern) { br_material* default_material; ... return(default_material); } ... { br_material* material; ... BrMaterialFindHook(&test_callback); material = BrMaterialFind("non_existent_material"); }See Also:
BrMaterialFindFailedLoad()
164
Description:
This function is provided as a suitable function to supply to BrMaterialFindFailedLoad()
BrMaterialFindHook()
163.
Declaration:
br_material* BrMaterialFindFailedLoad(const char* name)
Arguments:
const char * name
The name supplied to BrMaterialFind()
162.
Effects: Attempts to load the material from the filing system using
name
as the filename. Searches current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). If successful, sets this name as the identifier of the loaded material and adds the material to the registry.Result:
br_material *
Returns a pointer to the material, if found, else Null
.
Example:
BrMaterialFindHook(BrMaterialFindFailedLoad);
BrMaterialFileCount()
Declaration:
br_uint_32 BrMaterialFileCount(const char* filename, br_uint_16* num)
Arguments:
const char * filename
Name of the file containing the materials to count.
br_uint_16 * num
Pointer to the variable in which to store the number of materials counted in the file. If Null
, the file will still be located and appropriate success returned, but no count will be made.
Effects: Searches for
filename
, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). If a file is found, will count the number of materials stored in it.Result:
br_uint_32
Returns zero if the file was found (even if it is not a materials file), non-zero otherwise.
Name of the file containing the material to load.
Returns a pointer to the loaded material, or
Description:
Load a material. Note that it is not added to the registry.BrMaterialLoad()
br_material* BrMaterialLoad(const char* filename)
const char * filename
filename
, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).br_material *
Null
if unsuccessful.BrMaterialLoadMany()
165,
BrMaterialSave()
167
BrMaterialAdd()
158
.
Name of the file containing the materials to load.
A non-
Maximum number of materials to load.
Returns the number of materials loaded successfully. The pointer array supplied, is filled with pointers to the loaded materials.
Description:
Load a number of materials. Note that they are not added to the registry.BrMaterialLoadMany()
br_uint_32 BrMaterialLoadMany(const char* filename, br_material** materials, br_uint_16 num)
const char * filename
br_material ** materials
Null
pointer to an array of pointers to materials.br_uint_16 num
filename
, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).br_uint_32
BrMaterialFileCount()
164.
Description:
Load a material from a material script. Note that all maps and tables in a script should be already loaded and registered. If not, this function can be combined with BrFmtScriptMaterialLoad()
BrMapFindHook()
290 and
BrTableFindHook()
293
to facilitate rapid setup of materials with textures.
Declaration:
br_material* BrFmtScriptMaterialLoad(const char* filename)
Arguments:
const char * filename
Name of the file containing the material script.
Effects: Searches for
filename
, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).Result:
br_material *
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"; ];
BrFmtScriptMaterialLoadMany()
Declaration:
br_uint_32 BrFmtScriptMaterialLoadMany(const char* filename, br_material** materials, br_uint_16 num)
Arguments:
const char * filename
Name of the file containing a number of concatenated material script entries.
br_material ** materials
A non-Null
pointer to an array of pointers to materials.
br_uint_16 num
Maximum number of materials to load.
Effects: Searches for
filename
, if no path specified with file looks in current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined).Result:
br_uint_32
Return the number of materials loaded successfully. The pointer array if supplied, is filled with pointers to the loaded materials.
Name of the file to save the material to.
A pointer to a material.
Returns
Description:
Save a material to a file.BrMaterialSave()
br_uint_32 BrMaterialSave(const char* filename, const br_material* material)
const char * filename
const br_material * material
br_uint_32
Null
if the material could not be saved.BrWriteModeSet()
63
Name of the file to save the materials to.
A pointer to an array of pointers to materials. If
Number of materials to save.
Returns the number of materials saved successfully.
Description:
Save a number of materials to a file.BrMaterialSaveMany()
br_uint_32 BrMaterialSaveMany(const char* filename, const br_material* const* materials, br_uint_16 num)
const char * filename
const br_material * const * materials
Null
, all registered materials are saved (irrespective of num
).br_uint_16 num
br_uint_32
BrWriteModeSet()
63