Books and Pages

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-2008 by mental images GmbH