DB Functions

Database access functions can be used to convert pointers into tags, and to get the type of a tag. The scene database contains only tags and no pointers at all, because pointers are not valid on other machines. A tag is a 32-bit integer value that uniquely identifies a piece of data in mental ray's virtual shared database. It acts like a pointer except that it is valid across all machines on the network.

    int mi_db_type(
        const miTag tag)

Return the type of a database item. The tag must exist. Valid types that are of interest in shaders are:

    miSCENE_FUNCTION Function to call, such as a shading function  
    miSCENE_MATERIAL Material containing shaders and flags  
    miSCENE_LIGHT Light source  
    miSCENE_IMAGE Image in memory

The most important are functions and images, because general-purpose texture shaders need to distinguish procedural and image textures. See the texture shader example on page texshaderex.

    int mi_db_size(
        const miTag tag)

Return the size of a database item in bytes. The tag must exist. This function should be avoided if possible because it has poor performance and can lead to inefficient execution orders in mental ray 3.0 in certain situations.

    void *mi_db_access(
        const miTag tag)

Look up the tag in the database, pin it, and return a pointer to the referenced item. Pinning means that the database item is guaranteed to stay in memory at the same location until the item is explicitly unpinned. Rendering aborts if the given tag does not exist. mi_db_access always returns a valid pointer. If an item is accessed twice, it must be unpinned twice; pinned is a counter, not a flag. The maximum number of simultaneous pins on a single database element is 65535.

    void mi_db_unpin(
        const miTag tag)

Every tag that was accessed with mi_db_access must be unpinned with this function when the pointer is no longer needed. Failure to unpin can cause a pin overflow, which may abort rendering. After unpinning, the pointer may not be used any more.

    void mi_db_flush(
        const miTag tag)

This call is obsolete. It made the assumption that mi_db_access could be used for writing to data. This is no longer true. Do not use mi_db_flush.