PIXCON'S API

"keylist" is used to create a link list of data elements NOTE: this class does NOT free up the data elements when destroyed.

class keylist : public dbl_llist {

public:

void *key;

This data element contains a pointer to the data in this node. It is assumed that the programmer knows the type of this data.

virtual ~keylist();

"resource_type" is the base class for all geometric, material, and texture data.

class resource_type {

public:
char dataname[MAXSTRLEN];

This field contains the primary filename associated with the data in the object (if any).

char altname[MAXSTRLEN];

This field contains the secondary filename associated with the data in the object (if any). (Usually refers to data not in the primary file)

float access_time;

This field contains a hash time value that represents the last time this object was accessed for dynamically managed data.

unsigned int statusflag;

This field contains a mask of status flags for the current state of the object.

resource_type *next, *back;

These fields are used to implement a double link list.

resource_type();

virtual ~resource_type();

virtual void update(float current_time) = 0;

This method is used to dynamically managed memory by allocating/freeing blocks of data/memory to the system, based on current usage.

virtual void *query_data() = 0;

This method is used to access the dynamically managed memory, as well as update it's current status.

virtual void replace_data(void *subresource) = 0;

This method is used to set the dynamically managed memory.

"resource_manager" is a container class that manages groups of objects, from data to file format loaders. This class also performs dynamic data load management.

class resource_manager {

protected:
sfile sinfile;

This member is used to handle file i/o management

virtual void local_init();

This method is used to "initialize" the object w/r/t this class only

virtual void reset();

This method is used to "reset" the object w/r/t this class only

public:
resource_manager();

virtual ~resource_manager();

virtual void init(int x);

This method initializes the manager's data members. "x" is the number of frames to be kept in memory at a time - typically it is set to 1.

virtual void reset();

This method is used to free up non-static data elements to allow the manager to be reused for a different scene. This method is also activated by resource_manager::dest().

virtual void register_resource_object(int type, void *data);

This method is used to insert a data item into the resource container. "type" is a predefined identifier used for resource identification, and "data" is the data item to be inserted.

virtual void *find_resource_object(int type, char *id, char *alias);

This method is used to retrieve a data item. "type" is a predefined identifier used for resource identification, "id" is a character string used as a search key, and "alias" is a secondary search key.

virtual void *get_resource_object(int type);

This method is used to retrieve the data member from this class - usually the head of a list of data items. "type" is a predefined identifer used for resource identification.

virtual void update(float current_time);

This method is used to unload data elements that have not been accessed in a predetermined time frame.

"superclass" is the super parent class for most of the classes in Pixcon and defines the common characteristics for all these objects.

class superclass {

public:
int id;

Each object has a unique identifier assigned to it when instantiated.

superclass();

virtual ~superclass();

virtual int query_category();

This method returns a unique integer identifier used to group different classes and is generally used to identify which library it was written for. The Pixcon API reserves category identifiers in range of 0..999 for its own internal use.

virtual int query_whatami();

This method returns a unique integer identifier used to identify the class. The Pixcon API reserves class identifiers in the range of 0..999

virtual int query_whatwasi(int type);

This method is an extension of the query_whatami() method. This method is used to identify whether or not the current object inherits from a parent class who's query_whatami() returns "type".

virtual int parse(FILE *infile, char *token);

parse() is used by each object to identify "token", and to extract additional data from "infile" if necessary. If parse() successfully identifies the "token", it returns true, else it must call the nearest parent's version of parse() and returns to the caller the parent's return value.

virtual void preprocess(void *data);

After the object is initialized via constructors and parse(), this method is called to complete the initialization process. This method must also call its nearest parent's version of preprocess().

"frameclass" is used by objects that do not render in real time.

class frameclass : public superclass {

public:
int parse(FILE *infile, char *token);

A replacement for the virtual function defined in "superclass"

void preprocess(void *data);

A replacement for the virtual function defined in "superclass"

int frame;

This field is used to control at which frame this object is to be rendered

frameclass *next;

Each object is designed to be part of a linked list, and has a pointer to the "next" node in the list.

frameclass();

virtual ~frameclass();

virtual int dump_frame(FILE *outfile);

This function is used to dump the contents of this object into a file that is parseable by parse()

The class "loader" is the base class for a group of child classes whose purpose is to identify, instantiate, and parse a child class of superclass.

class loader : public dbl_llist {

protected:

char *object_name;

This field contains a pointer to a character string used to identify the loader and/or object it instantiates.

virtual superclass *make_object() = 0;

This virtual function allocates and returns an instance of the object it was designed for. The caller is responsible for deleting the allocated object.

public:

loader();

virtual ~loader();

char *query_name();

This method provides access to the "object_name" field.

virtual superclass *parse(FILE *infile, char *token);

This method uses "token" to identify if this loader is to be used. If not, it passes it's arguments to the "next" loader if the pointer is valid, else returns NULL. If this method identifies "token", it instantiates an instance of the object to be parsed, then passes the "infile" file pointer off to the object's parse() method and returns the allocated object.

The "doer" class is designed to store and manage callback function pointers in a binary tree. Each callback has a string identifier, and an optional initialization function. The callback has only one argument, of type (void *), which passes the address of a user defined data structure. The initialization function has no arguments.

class doer : public string_binary_data {

protected:

void *fcn;

This field contains a pointer to the callback function.

void *init_fcn;

This field contains a pointer to an initalization function - to be activated automaticly before the callback is used. If this field is not set, it is assumed that there is no initialization function.

public:

virtual ~doer();

doer *find(char *target);

This method searches for "target" w/in each node in the tree. If successful, it returns the corresponding node, otherwise returns NULL.

int set(char *tmpstr, void *func_call, void *init_call = (void *)NULL);

This method sets the search string, callback, and its optional initialization function.

int query_data(void *x);

This method activates the callback w/ "x" as its input argument.

void init();

If an intialization function has been set, this method activates it.

The "dbl_llist" class is designed store data in a double linked list. For the most part, the methods in this base class should not be accessed directly w/o extreme caution - instead use dbl_llist_manager to build/manipulate/destroy your lists.

class dbl_llist {

public:

dbl_llist *next, *back;

This is the next and back pointers to the adjacent nodes in the list.

dbl_llist();

virtual ~dbl_llist();

void dest();

This method is a quick and dirty way of destroying the part of the list associated w/ the "next" pointer.

virtual void insert(dbl_llist *x);

This method associates the new node "x" w/ the "back" pointer.

virtual void append(dbl_llist *x);

This method associates the new node "x" w/ the "next" pointer.

virtual void remove(); This method disengages this node from the list.

The "dbl_llist_manager" class is designed safely manipulate the dbl_llist objects, minimizing memory leaks and garbage lists.

class dbl_llist_manager {

public:
dbl_llist *head, *tail;

These fields are pointers that represent the head node and tail node of the double link list, initially set to NULL.

int count;

This field contains a count of the # of objects in the list

dbl_llist_manager();

virtual ~dbl_llist_manager();

void dest();

This method deallocates the entire list - returning the objects to the memory manager

virtual dbl_llist *insert(dbl_llist *x, dbl_llist *target);

This method inserts the new node "x" into the list. If "target" is "NULL", "x" is placed at the head of the list, otherwise "x" is inserted before "target". The "head"/"tail" fields are adjusted if need be. The return value is "x".

virtual dbl_llist *append(dbl_llist *x, dbl_llist *target);

This method appends the new node "x" into the list. If "target" is "NULL", "x" is placed at the tail of the list, otherwise "x" is appended after "target". The "head"/"tail" fields are adjusted if need be. The return value is "x".

virtual int remove(dbl_llist *x);

This method removes "x" from the list and is not intended to return "x" to the memory manager. The return value is "0" if it was unable to be removed from the list.

The "circular_dbl_llist" class is designed store data in a circular double linked list, where the "head" field is generally considered the current access point into the list, and the "tail" field is invalid. For the most part, the methods in this base class should not be accessed directly w/o extreme caution - instead use circular_dbl_llist_manager to build/manipulate/destroy your lists.

class circular_dbl_llist : public dbl_llist {

public:
void insert(dbl_llist *x);

This method inserts the new node "x" into the list. If "target" is "NULL", "x" is inserted before the current "head" of the list and becomes the new "head", otherwise "x" is inserted before "target".

void append(dbl_llist *x);

This method appends the new node "x" into the list. If "target" is "NULL", "x" is inserted before the current "head" - note no adjustment of the "head" field, otherwise "x" is appended after "target".

void remove();

This method removes "x" from the list and is not intended to return "x" to the memory manager.

The "circular_dbl_llist_manager" class is designed safely manipulate the circular_dbl_llist objects, minimizing memory leaks and garbage lists.

class circular_dbl_llist_manager {

public:
circular_dbl_llist *head;

This field is a pointer that represent the head node of the circular double link list, initially set to NULL.

int count;

This field contains a count of the # of objects in the list

circular_dbl_llist_manager();

virtual ~circular_dbl_llist_manager();

void dest();

This method deallocates the entire list - returning the objects to the memory manager

void make_head(circular_dbl_llist *x);

This method makes "x" the current head of the list. It is assumed that "x" is in the list.

virtual circular_dbl_llist *append(circular_dbl_llist *x, circular_dbl_llist *target = NULL);

This method appends the new node "x" into the list. If "target" is "NULL", "x" is placed before the "head", otherwise "x" is appended after "target". The return value is "x".

virtual circular_dbl_llist *insert(circular_dbl_llist *x, circular_dbl_llist *target = NULL);

This method inserts the new node "x" into the list. If "target" is "NULL", "x" is placed before the "head", and the "head" field is set to it, otherwise "x" is inserted before "target". The return value is "x".

virtual int remove(circular_dbl_llist *x);

This method removes "x" from the list and is not intended to return "x" to the memory manager.

The "binary_data" class is used as a parent class for storing and evaluating data used in calculating the placement of a binary_node object in a binary_tree object.

class binary_data {

public:
virtual ~binary_data();

virtual int compare(binary_data *x) = 0;

This method is used to determine if "this" is considered less than, equal, or greater than "x", and returns -1, 0, 1 respectively

The "binary_node" class represents a node in a binary_tree

class binary_node {

public:
binary_data *key;

This field contains the "key" which will determine the nodes placement in the tree

binary_node *next, *back;

These fields contain the pointers to the left and right childs of this node

binary_node();

virtual ~binary_node();

virtual binary_node *insert(binary_node *x);

This method is used to insert "x" into the subtree headed by this node. If successful, it returns "x" else "NULL"

int remove(binary_node *x);

This method is used to remove references to "x" in the tree, but does not return it to the memory manager. It returns 0 if unsuccessful

virtual binary_node *find(binary_data *x);

This method is used find a node in this subtree that has a matching key to "x". If successful, it returns the "node", else "NULL".

The "binary_tree" class manages a binary tree built w/ binary_node objects

class binary_tree {

public:
binary_node *head;

This field points to the head of the tree of binary_nodes

void dest();

This method destroys the tree of nodes and returns them to the memory manager

binary_tree();

virtual ~binary_tree();

virtual binary_node *insert(binary_node *x);

This method inserts "x" into the tree, using its key to find its proper place. The return value is dependant on the implementation of the binary_node or its child class, but is usually "x"

virtual int remove(binary_node *x);

This method removes all references to "x" from the tree, but doesn't return it to the heap. If successful, it returns 1 else 0

binary_node *find(binary_data *x);

This method looks for a match for "x" and if successful, returns the binary_node that contains it.

The "string_type" class manages a resizeable character string

class string_type : public dbl_llist {

protected:
int size;

This field contains the actual amount of memory allocated for the character string.

int length;

This field contains the length of the character string

public:

char *string;

This field contains point to the character string

string_type();

string_type(char* src);

virtual ~string_type();

int stringlen();

This method returns the length of the string

void stringsize(int len);

This method extends the string size (if needed) to at least "len" bytes

int recalc();

This method does some internal recalculations - used if the user manipulates the string other than the provided methods. It returns 1 if successful, else 0

void reset();

This method essentially sets the string as a "NULL" string.

char *stringcpy(char *src);

This method copies the data from "src", resizing the destination buffer if necessary. Returns the copied string.

char *stringncpy(char *src, int len);

This method copies the data from "src" up to "len" bytes, resizing the destination buffer if necessary. Returns the copied string.

char *stringcpy(string_type *src);

This method copies the data from "src", resizing the destination buffer if necessary. Returns the copied string.

char *stringcat(char *src);

This method concatinates the data from "src" to the current string, resizing the destination buffer if necessary. Returns the cat'ed string.

char *stringcat(string_type *src);

This method concatinates the data from "src" to the current string, resizing the destination buffer if necessary. Returns the cat'ed string.

int stringcmp(char *str);

This method compares the current string to "str" returning -1 (less than), 0 (equal), 1 (greater than)

int stringcmp(string_type *str);

This method compares the current string to "str" returning -1 (less than), 0 (equal), 1 (greater than)

The "buffer_type" class manages a resizeable memory buffer

class buffer_type : public dbl_llist {

protected:

int size;

This field contains the actual amount of memory allocated for the buffer.

int length;

This field contains the requested length of the buffer

public:

char *data;

This field points to the memory buffer

buffer_type();

virtual ~buffer_type();

int bufferlen();

This method returns the last requested memory length

void bufferlen(int len);

This sets the buffer length

int buffersize();

This method returns the actual size of the buffer

void buffersize(int len);

This method sets the actual size of the buffer

char *buffercpy(char *src, int len);

This method copies "len" bytes of "src" into the buffer, resizing if need be

char *buffercpy(buffer_type *buff);

This method copies "buff" into the buffer, resizing if need be

The "string_binary_data" class uses string_type as a key for placement bye the binary_tree manager

class string_binary_data : public binary_data {

public:

int compare(binary_data *x);

A replacement for the virtual function defined in "binary_data".

string_type string;

virtual ~string_binary_data();