BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_material
Next|Prev|Up
The Structure
Members
Copy/Assign
Access & Maintenance
BrMaterialAdd()
BrMaterialAddMany()
BrMaterialUpdate()
BrMaterialRemove()
BrMaterialRemoveMany()
Referencing & Lifetime
Initialisation
Construction & Destruction
BrMaterialAllocate()
BrMaterialFree()
Supplementary
BrMaterialCount()
BrMaterialEnum()
BrMaterialFind()
BrMaterialFindMany()
BrMaterialFindHook()
BrMaterialFindFailedLoad()
Import & Export
BrMaterialFileCount()
BrMaterialLoad()
BrMaterialLoadMany()
BrFmtScriptMaterialLoad()
BrFmtScriptMaterialLoadMany()
BrMaterialSave()
BrMaterialSaveMany()
Platform Specific

br_material

The Structure

A structure describing the appearance of a material that can be applied to a surface.

The typedef

(See material.h for precise declaration and ordering)

Behaviour

br_uint_32 flags Flags determining how this material is rendered

Lighting

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

Colour

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)

Texture

br_pixelmap * colour_map An optional pixel map based texture

br_matrix23 map_transform Transform to apply to texture map

Supplementary

char * identifier Material name

void * user User data (application dependent)

Related Functions

Scene Modelling

See BrEnvironmentSet()85, BrModelApplyMap()231, BrModelFitMap()233.

Scene Rendering

See BrZbModelRender()249.

Related Structures

Scene Modelling

See br_actor74, br_model228, br_face122, br_vertex367.

Scene Rendering

See br_renderbounds_cbfn307, br_model_custom_cbfn247.

Members

Behaviour

br_uint_32 flags

This member determines how faces using the material are rendered, in terms of other members and aspects of the scene.

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

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

br_ufraction ka

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.

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.

br_ufraction kd

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.

Zero can give a shiny surface, whereas higher values can give surfaces a more matt appearance.

br_ufraction ks

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

The greater the value, the more visible highlights will be.

br_scalar power

This member applies a power to the specular lighting contribution.

The greater the value, the sharper any highlights will be. A typical value is 20.

Colour

br_colour 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_MATF_LIGHT is set, but not BR_MATF_PRELIT).

br_uint_8 index_base

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

This member only applies to materials without textures - with textures, this member is ignored.

br_uint_8 index_range

When rendering in indexed colour, this member determines the number of index values that can be selected with a given lighting level, starting at index_base.

This member only applies to materials without textures - with textures, this member is ignored.

br_pixelmap * index_shade

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.

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.

BR_PMT_INDEX_8 shade table to BR_PMT_INDEX_8 output

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.

BR_PMT_RGB_555 shade table to BR_PMT_RGB_555 output

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.

BR_PMT_RGBX_888 shade table to BR_PMT_INDEX_8 output

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.

  1. X1=Red component of pixel in shade table at column(Texel), row(Red light level)

  2. X2=Green component of pixel in shade table at column(X1), row(Green light level)

  3. X3=Blue component of pixel in shade table at column(X2), row(Blue light level)

  4. Ouput pixel is X3

br_pixelmap * index_blend

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.

Thus an 8 bit indexed colour texture map blend table needs 256 columns and 256 rows. The blend table is only used if BR_MATF_BLEND is set, and if set this member should not be Null.

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.

Texture

br_pixelmap * colour_map

A pointer to a pixel map containing a pattern with which to cover faces using this material.

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 index_blend above.

Note that indexed colour textures must also have a corresponding shade table.

br_matrix23 map_transform

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.

See BrModelApplyMap()231 for details of how texture maps can be applied to a model's faces.

Supplementary

char * identifier

Pointer to unique, zero terminated, character string (or 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

This member may be used by the application for its own purposes. It is initialised to Null upon allocation, and not accessed by BRender thereafter.

Copy/Assign

The br_material151 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.

Access & Maintenance

Materials must be added to the registry if they are involved in rendering a scene. They should not be modified during rendering.

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.

BrMaterialAdd()

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.

Declaration:
br_material* BrMaterialAdd(br_material* material)

Arguments:
br_material * material

A pointer to a material.

Result:
br_material *

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

See Also:
BrMaterialUpdate()159, BrMaterialAddMany()158, BrMaterialLoad()165, BrMaterialFind()162, BrMaterialRemove()159.

BrMaterialAddMany()

Description:
Add a number of materials to the registry, updating them as necessary.

Declaration:
br_uint_32 BrMaterialAddMany(br_material* const* materials, int n)

Arguments:
br_material * const * materials

A pointer to an array of pointers to materials.

int n

Number of materials to add to the registry.

Result:
br_uint_32

Returns the number of materials added successfully.

See Also:
BrMaterialUpdate()159, BrMaterialAdd()158, BrMaterialRemove()159, BrMaterialRemoveMany()159

BrMaterialUpdate()

Description:
Update a material that has changed in some respect since the previous update of this material (or 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.

BrMaterialRemove()

Description:
Remove a material from the registry.

Declaration:
br_material* BrMaterialRemove(br_material* material)

Arguments:
br_material * material

A pointer to a material.

Result:
br_material *

Returns a pointer to the item removed.

See Also:
BrMaterialAdd()158

BrMaterialRemoveMany()

Description:
Remove a number of materials from the registry.

Declaration:
br_uint_32 BrMaterialRemoveMany(br_material* const* materials, int n)

Arguments:
br_material * materials

A pointer to an array of pointers materials.

int n

Number of materials to remove from the registry.

Result:
br_uint_32

Returns the number of items removed successfully.

See Also:
BrMaterialAddMany()158

Referencing & Lifetime

Materials may be multiply referenced. The texture map and any shade table may be referenced by more than one material as long as their lifetimes are longer than the materials that refer to them. Materials must have been added to the registry if they will be involved in rendering. The material must be maintained while it is in the registry or being referenced.

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.

BrMaterialAllocate()

Description:
Allocate a new material.

Declaration:
br_material* BrMaterialAllocate(const char* name)

Arguments:
const char * name

String to initialise the identifier member to.

Result:
br_material *

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

BrMaterialFree()

Description:
Deallocate a material and any associated memory.

Declaration:
void BrMaterialFree(br_material* m)

Arguments:
br_material * m

A pointer to a material.

Supplementary

BrMaterialCount()

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

Declaration:
br_uint_32 BrMaterialCount(const char* pattern)

Arguments:
const char * pattern

Search pattern.

Result:
br_uint_32

Returns the number of items matching the search pattern.

See Also:
BrMaterialEnum()161, BrMaterialFind()162

BrMaterialEnum()

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 br_uint_32348 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()

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

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

BrMaterialFindMany()

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

Declaration:
br_uint_32 BrMaterialFindMany(const char* pattern, br_material** materials, int max)

Arguments:
const char * pattern

Search pattern.

br_material ** materials

A pointer to an array of pointers to materials.

int max

Maximum number of materials to find.

Result:
br_uint_32

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

See Also:
BrMaterialFind()162, BrMaterialFindHook()163

BrMaterialFindHook()

Description:
Functions to set up a call-back.

Declaration:
br_material_find_cbfn* BrMaterialFindHook(br_material_find_cbfn* hook)

Arguments:
br_material_find_cbfn * hook

A pointer to a call-back function.

Effects:
If 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

BrMaterialFindFailedLoad()

Description:
This function is provided as a suitable function to supply to 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);

Import & Export

BrMaterialFileCount()

Description:
Locate a given file and count the number of materials in it.

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.

BrMaterialLoad()

Description:
Load a material. Note that it is not added to the registry.

Declaration:
br_material* BrMaterialLoad(const char* filename)

Arguments:
const char * filename

Name of the file containing the material 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_material *

Returns a pointer to the loaded material, or Null if unsuccessful.

See Also:
BrMaterialLoadMany()165, BrMaterialSave()167, BrMaterialAdd()158.

BrMaterialLoadMany()

Description:
Load a number of materials. Note that they are not added to the registry.

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

Arguments:
const char * filename

Name of the file containing the materials to load.

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

Returns the number of materials loaded successfully. The pointer array supplied, is filled with pointers to the loaded materials.

See Also:
To determine how many materials are stored in a file see BrMaterialFileCount()164.

BrFmtScriptMaterialLoad()

Description:
Load a material from a material script. Note that all maps and tables in a script should be already loaded and registered. If not, this function can be combined with BrMapFindHook()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()

Description:
Load a number of materials from a material script.

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.

BrMaterialSave()

Description:
Save a material to a file.

Declaration:
br_uint_32 BrMaterialSave(const char* filename, const br_material* material)

Arguments:
const char * filename

Name of the file to save the material to.

const br_material * material

A pointer to a material.

Effects:
Writes the material to a file*2.

Result:
br_uint_32

Returns Null if the material could not be saved.

See Also:
BrWriteModeSet()63

BrMaterialSaveMany()

Description:
Save a number of materials to a file.

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

Arguments:
const char * filename

Name of the file to save the materials to.

const br_material * const * materials

A pointer to an array of pointers to materials. If Null, all registered materials are saved (irrespective of num).

br_uint_16 num

Number of materials to save.

Effects:
Writes the materials to a file*3.

Result:
br_uint_32

Returns the number of materials saved successfully.

See Also:
BrWriteModeSet()63

Platform Specific

The supported combinations of material flags vary from platform to platform. The supported dimensions of texture maps are also platform dependent.

Generated with CERN WebMaker