3Delight 8.5 User's Manual: 9.8 Ri Plug-in Filters API

Short Contents

9.8 Ri Plug-in Filters API

All Rif API function and class definitions are defined in `$DELIGHT/include/rif.h', so this file must be #included. API entry points are described in the following sections.

Plug-in Entry Points

The following functions should be defined in all Ri plug-in filters.

RifPlugin* RifPluginManufacture ( int argc, char **argv )

This function is called after the plug-in is loaded. It should return an instance of the Ri plug-in filter. An example is provided in Listing 7.15. All parameters are passed using i_argc and i_Argv as for the main() in C. The RiPlugin abstract class is defined in `$DELIGHT/include/rif.h' and all plug-in filters must derive from it:

class RifPlugin
{
public:
    virtual ~RifPlugin() {}
    virtual RifFilter &GetFilter() = 0;
};

The RifFilter structure returned by RifPlugin::GetFilter() contains all the filtering information (refer to Using Ri Plug-in Filters for usage examples):

struct RifFilter
{
    enum { k_UnknownVersion = 0, k_CurrentVersion = 1 };
    enum { k_Continue = 1, k_Terminate = 2 } DefaultFiltering;
    int Filtering;
    short Version;
    void *ClientData;
    char Reserved[64];
    RifFilter();
    /* Transforms */
    RtVoid (*Perspective)(RtFloat fov);
    RtVoid (*ConcatTransform)(RtMatrix transform);
    RtVoid (*CoordinateSystem)(RtToken space);
    RtVoid (*ScopedCoordinateSystem)(RtToken space);
    RtVoid (*CoordSysTransform)(RtToken space);
    RtVoid (*Identity)(void);
    ... 
};

RtVoid RifPluginDelete ( RifPlugin* i_plugin ): It is recommended to have this entry point in the DSO, since 3DELIGHT will use it to destroy DSOs loaded using RifLoadPlugin() (see below). This function has been defined for Windows systems, were memory allocation and deallocation cannot span multiple DLLs. The Plug-in will still work without this entry point but will leak memory on Windows systems.

Renderer's Entry Points

The following functions are implemented in 3DELIGHT and are accessible from Ri plug-ins.

RifPlugin* RifLoadPlugin ( const char *i_name, int i_argc, char **argv ): Loads the Ri plug-in specified named i_name and add it at the end of the plug-in chain. It is necessary to call RifUnloadPlugins() to free all allocated resources at the end of render.

RtVoid RifUnloadPlugins ( void ): Free all allocated resources and close all DSOs that have been loaded by RifLoadPlugin().

RtVoid RifAddPlugin ( RifPlugin *i_plugin ): Add a plug-in at the end of the plug-in chain. The user is responsible of the actual loading and resource management tasks. It is suggested to use RifLoadPlugin() instead.

RifPlugin* RifGetCurrentPlugin ( ): Returns the currently active plug-in. This function is important since there is no way, for the plug-in, on which particular instance it is running (because all callbacks are static).

RifEmbedding RifGetEmbedding ( )

Says whether this plug-in is run in RIB output mode or in normal rendering mode. For example, when executing renderdl with the `-catrib' option, plug-ins are in RIB output mode. A particular plug-in might choose to act differently depending on the "embedding". RifEmbedding is defined as follows:

typedef enum
{
    k_RifRIB,
    k_RifRenderer
} RifEmbedding;

RtInt RifGetDeclaration ( RtToken i_token, RifTokenType *i_token, RifTokenDetail *i_detail, RtInt *o_array_len ): A helper function to parse Ri in-line declarations.

RtVoid RifGetChainInfo (RtInt *o_current, RtInt *o_total ): This procedure returns the current level in the Ri plug-in filter chain as well as the total number of plug-ins in the chain. Range of the o_current variable is [0 ... o_total-1]

RtVoid RifParseFile (const char *i_filename, RifParseMode i_mode )

This procedure enables a Ri plug-in to easily parse RIB files. The i_mode variables tells 3DELIGHT where, in the Ri plug-in filter chain, the RIB stream should be inserted:

k_RifParseNextLayer: Inject RIB stream into next plug-in filter in the chain.
k_RifParseThisLayer: Inject RIB stream back into this layer in the chain.
k_RifParseFirstLayer: Inject RIB stream into first layer in the chain.

The declaration of RifParseMode is found in `$DELIGHT/include/rif.h':

typedef enum
{
    k_RifParseNextLayer,
    k_RifParseThisLayer, 
    k_RifParseFirstlayer
} RifParseMode;

RtVoid RifParseBuffer (const char *i_buf, unsigned i_size, RifParseMode i_mode ): Same as RifParseFile but parse RIB commands from memory.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]