BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_resource_class
Next|Prev|Up
The Structure
Members
Operations
BrResClassAdd()
BrResClassAddMany()
BrResClassRemove()
BrResClassRemoveMany()
Copy/Assign
Access & Maintenance
Referencing & Lifetime
Initialisation
Construction & Destruction
Supplementary
BrResClassFind()
BrResClassFindMany()
BrResClassFindHook()
BrResClassCount()
BrResClassEnum()

br_resource_class


The Structure

This structure is used for application defined resource classes.

Once the structure is initialised, it is registered using BrResClassAdd()325, thereafter allowing application defined memory or resource classes to be used.

The typedef

(See brmem.h for precise declaration and ordering)

Primary

br_uint_8 res_class Resource memory class

br_resourcefree_cbfn* free_cb Resource destructor

Supplementary

char * identifier Resource class name

Related Functions

Resource Management

See BrResAllocate()48, BrResFree()51, BrResAdd()49, BrResRemove()51, BrResStrDup()49, BrResSize()50, BrResClass()49, BrResChildEnum()50.

Memory Management

See BrMemAllocate()55, BrMemCalloc()55, BrMemInquire()55, BrMemFree()56, BrMemStrDup()55.

Related Structures

Memory Management

See br_allocator99.

Members

Primary

br_uint_8 res_class

The memory class of the new resource class. See Memory Classes for a description of possible values. Only values between
BR_MEMORY_APPLICATION+1 and BR_MEMORY_MAX-1 (inclusive) should be used.

br_resourcefree_cbfn * free_cb

This is a pointer to the destructor function (See br_resourcefree_cbfn331) it may be Null if not required. Note that this function is not used to free the memory of the resource. It is simply an opportunity for the application to perform any other housekeeping functions indicated by the destruction of the resource. The resource is destroyed after the destructor returns.

For example, a user defined resource may be of structures containing pointers to reference counted (non-resource) items. In such a case, the referenced item will need to be dereferenced.

Supplementary

char * identifier

Pointer to unique, zero terminated, character string (or Null if not required). A string constant is recommended. The alternative is to use something like:

my_res_class=BrResAllocate(NULL,sizeof(br_resource_class),
                                BR_MEMORY_RESOURCE_CLASS);
my_res_class->identifier=BrResStrDup(my_res_class,"MyClass");

Operations


BrResClassAdd()

Description:
Create a new resource class.

Declaration:
br_resource_class* BrResClassAdd(br_resource_class* rclass)

Arguments:
br_resource_class * rclass

A non-Null pointer to a resource class. The res_class member of rclass must be set to a valid, unused class ID between BR_MEMORY_APPLICATION+1 and BR_MEMORY_MAX-1 (inclusive).

Preconditions:
Between BrBegin()10 & BrEnd()11.

Result:
br_resource_class *

Returns a pointer to the resource class or Null if unsuccessful.

Remarks:
Remember, that rclass must point to a resource class structure that will remain valid until the class is removed.


BrResClassAddMany()

Description:
Create several new resource classes.

Declaration:
br_uint_32 BrResClassAddMany(br_resource_class* const* items, int n)

Arguments:
br_resource_class * const * items

A non-Null pointer to a series of pointers to resource classes. The res_class member of each resource class structure pointed to by items must be set to a valid, unused class ID between BR_MEMORY_APPLICATION+1 and BR_MEMORY_MAX-1 (inclusive).

int n

Number of new resource classes to create.

Preconditions:
Between BrBegin()10 & BrEnd()11.

Result:
br_uint_32

Returns the number of resource classes successfully created.

Remarks:
Remember, that each resource class structures must remain valid until it is removed.


BrResClassRemove()

Description:
Remove a resource class from use.

Declaration:
br_resource_class* BrResClassRemove(br_resource_class* rclass)

Arguments:
br_resource_class * rclass

A non-Null pointer to a resource class (that has been previously created using BrResClassAdd()325).

Preconditions:
Between BrBegin()10 & BrEnd()11.

Result:
br_resource_class *

Returns a pointer to the removed resource class.


BrResClassRemoveMany()

Description:
Remove a number of resource classes from use.

Declaration:
br_uint_32 BrResClassRemoveMany(br_resource_class* const* items, int n)

Arguments:
br_resource_class * const * items

A non-Null pointer to an array of pointers to resource classes (all having previously been created using BrResClassAdd()325).

int n

Number of resource classes to remove from use.

Preconditions:
Between BrBegin()10 & BrEnd()11.

Result:
br_uint_32

Returns the number of resource classes successfully removed from use.


Copy/Assign

Beware of copying the structure if identifier has been allocated from the heap. Do not use the same structure for different resource classes.

Access & Maintenance

While a current resource class, the members should not be changed. No maintenance required.

Referencing & Lifetime

The structure must remain valid until the class is removed using BrResClassRemove()326. BRender will not necessarily make a copy of the br_resource_class324 structure.

Initialisation

The members should be set before the structure is passed to BrResClassAdd()325.

Construction & Destruction

The structure should ideally be statically constructed, but could be constructed and destroyed as in the following code:

br_resource_class* my_res_class;
my_res_class=BrResAllocate(NULL,sizeof(br_resource_class),
                                BR_MEMORY_RESOURCE_CLASS);
...	/* Set members */
#define MY_RES_CLASS BR_MEMORY_APPLICATION+1
my_res_class->res_class=MY_RES_CLASS;
my_res_class->free_cb=NULL;
my_res_class->identifier="MyResClass";

BrResClassAdd(my_res_class);
...
BrResFree(my_res_class);

Supplementary

The identifier may be used to specify a resource class by name. Not recommended for intensive use. Locate resources, and keep a record of pointers. The following functions provide searching, counting and enumeration facilities for resource classes.


BrResClassFind()

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

Declaration:
br_resource_class* BrResClassFind(const char* pattern)

Arguments:
const char * pattern

Search pattern.

Result:
br_resource_class *

Returns a pointer to the resource class if found, otherwise NULL. If a call-back exists and is called, the call-back's return value is returned.


BrResClassFindMany()

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

Declaration:
br_uint_32 BrResClassFindMany(const char* pattern, br_resource_class** items, int max)

Arguments:
const char * pattern

Search pattern.

br_resource_class ** items

A pointer to an array of pointers to resource classes.

int max

The maximum number of resource classes to find.

Result:
br_uint_32

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


BrResClassFindHook()

Description:
Set up a resource class find call-back. If BrResClassFind()
328 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 resource class.

Declaration:
br_resclass_find_cbfn* BrResClassFindHook(br_resclass_find_cbfn* hook)

Arguments:
br_resclass_find_cbfn * hook

A pointer to a call-back function.

Result:
br_resclass_find_cbfn *

Returns a pointer to the old call-back 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");
}


BrResClassCount()

Declaration:
br_uint_32 BrResClassCount(const 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 wild cards `*' and `?'.

Arguments:
const char * pattern

Search pattern.

Result:
br_uint_32

Returns the number of resource classes matching the search string.


BrResClassEnum()

Description:
Call a call-back function for every resource class matching a given search pattern. The call-back 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 wild cards `*' and `?'. The call-back itself returns a br_uint_32
348 value. The enumeration will halt at any stage if the return value is non-zero.

Declaration:
br_uint_32 BrResClassEnum(char* pattern, br_resclass_enum_cbfn* callback, void* arg)

Arguments:
char * pattern

Search pattern.

br_resclass_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, 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);
}



Generated with CERN WebMaker