| Element type: | miSCENE_BOOK |
| Data type: | miBook |
| Sizes: | miGeoIndex line_size, no_lines |
| Defaults: | all nulls except where otherwise noted |
#define miSCENE_BOOK_MAXSWAP 16
typedef struct miBook {
miUint label; /* type of book */
miGeoIndex no_pages; /* number of used pages */
miGeoIndex first_page_size;/* number of lines on first page */
miGeoIndex line_size; /* size of elments in bytes */
miGeoIndex next_free_line; /* index of next free line */
miGeoIndex last_used_line; /* index of last used line */
char swap[miSCENE_BOOK_MAXSWAP];
/* string for change of byte order */
miTag next_book; /* tag for next book */
miTag pages[1]; /* array of page tags */
} miBook;
When a box is created the line size and the swap string must be supplied. The number of lines influences the size of the page. If it is smaller than some threshold a default page size is used.
label is a variable at the disposal of the application using miBooks. It is not used by any of the book management functions described below.
no_pages is the number of used memory pages.
first_page_size is the number of lines on the first page. Consecutive pages grow in geometric progression. The details are implementation dependent and may change in the future.
line_size is the size of the lines in bytes in the current book.
next_free_line is the index of the element of the linked list of free lines.
last_used_line helps mental ray to manage books more efficiently.
swap is string of at most miSCENE_BOOK_MAXSWAP - 1 characters which indicates how the bytes in a line of a book should be swapped when being transferred between machines of different byte order.
next_book is a tag that allows to build chains of books. These may be accessed and enumerated more efficiently than single books.
pages is an array of page tags. It is guaranteed to be big enough to hold all pages that might be allocated to keep the maximum total number of miMAX_GEOINDEX lines.
None of the structure elements above except the label should be accessed directly. The same applies to the pages the books consist of.
| Element type: | miSCENE_PAGE |
| Data type: | miPage |
| Sizes: | miGeoIndex page_size, line_size |
| Defaults: | all nulls except where otherwise noted |
typedef struct miPage {
char swap[miSCENE_BOOK_MAXSWAP];
/* string for change of byte order */
miGeoIndex page_size; /* number of lines on current page */
miGeoIndex line_size; /* size of elments in bytes */
} miPage;
When a page is created the page and line sizes and the swap string must be supplied. However, pages should not be created directly but only through the calls to manage books described below.
swap is a string to indicate how lines should be swapped when pages are transferred between machines of different byte order. It has to stored in the pages too, because they are swapped independently of the books.
page_size is the number of lines on the current page.
line_size is the size of the lines on this page in bytes.
Apart from the SCENE call interface function to create books etc., there are a number of extra functions to manage books:
void *mi_scene_book_get_line(
miBook *book,
miGeoIndex line_num)
Access a line with index line_num of a given book and returns a void pointer to it.
void *mi_scene_book_allocate_line(
miBook *book,
miGeoIndex *line_num)
Return a void pointer to a free element in a given book and set the line_num passed by reference. This may be a yet unused line or one that has been previously deleted with a call to mi_scene_book_release_line. If the lines on existing pages are exceeded a new page is allocated.
void mi_scene_book_release_line(
miBook *book,
miGeoIndex line_num)
Delete a line from a given book.
void mi_scene_book_enumerate(
miBook *book,
void (*cb_func)(void *,
miGeoIndex,
void *),
void *cb_data)
Look at each element in a book in turn and if it is in use executes a call-back function. mi_scene_book_enumerate takes three arguments. The first is a pointer to an miBook, the second a pointer to the call-back function, and the third a pointer to optional data that are passed to the call-back when it is called. If either the book or the call-back pointer is NULL nothing is done. Otherwise the book is traversed and for each valid element the function pointed to by the second argument is called. The argument of this call-back function are a pointer to the element in the book, its index and the optional data pointer. An element in a book is valid if it has been allocated by a call to mi_scene_book_allocate_line and not been freed subsequently by a call to mi_scene_book_release_line. Neither the call-back function nor mi_scene_book_enumerate return a value.
miGeoIndex mi_scene_book_free_blk_start(
miBook *book)
Return the index of the first line in the completely unused part of a book.
miGeoIndex mi_scene_book_no_used_lines(
miBook *book)
Return the number of used lines in a book.
miGeoIndex mi_scene_book_max_lines(
miBook *book)
Return the maximum allocated number of lines in a book.
miBoolean mi_scene_book_line_valid(
miBook *book,
miGeoIndex line)
Return miTRUE if a given line index refers to a used line and miFALSE otherwise.
miTag mi_scene_book_attach(
miTag old_book,
miTag new_book,
miGeoIndex position)
Concatenate chains of books. Insert the new book at the specified position in the chain and returns the tag of the first book in the chain after insertion.
miTag mi_scene_book_detach(
miTag book,
miGeoIndex position)
Split off a component from a chain of books. Return the tag of the first book in the remaining chain.
Copyright © 1986-2009 by mental images GmbH