3Delight 8.5 User's Manual: 9.6 The Rx API

Short Contents

9.6 The Rx API

The Rx library provides access to some useful internal functions to SL DSOs writers. Also, it allows RiProcedural writers to query internal state of the renderer.

9.6.1 Noise functions

There are three noise functions. They access respectively the internal implementations of noise, pnoise and cellnoise in the shading language (see section Noise and Random). They are accessible to both DSO shadeops and RiProcedural code.

RtInt RxNoise ( RtInt i_inDimension, RtFloat *i_in, RtInt i_outDimension, RtFloat *o_out )
RtInt RxPNoise ( RtInt i_inDimension, RtFloat *i_in, RtFloat *i_period, RtInt i_outDimension, RtFloat *o_out )
RtInt RxCellNoise ( RtInt i_inDimension, RtFloat *i_in, RtInt i_outDimension, RtFloat *o_out ): As input, these functions take one to four floats. The number of floats is passed by i_inDimension and the values by i_in. The expected number of dimensions as a result should be passed by i_outDimension (only one and three are accepted). It is important to provide a big enough o_out buffer to contain the output. The i_period parameter for RxPNoise should contain as many periods as there are input dimensions. A return value of `0' indicates a sucess.

9.6.2 Texture lookup functions

There are three texture lookup functions. They call respectively the implementations of environment, shadow and texture in the shading language (see section Texture Mapping). Texture functions are only accessible through DSO shadeops.

RtInt RxEnvironment ( RtString i_fileName, RtInt i_firstChannel, RtInt i_nChannels, RtPoint i_dir0, RtPoint i_dir1, RtPoint i_dir2, RtPoint i_dir3, RtFloat *o_result, ... )
RtInt RxShadow ( RtString i_fileName, RtInt i_firstChannel, RtPoint i_P0, RtPoint i_P1, RtPoint i_P2, RtPoint i_P3, RtFloat *o_result, ... )
RtInt RxTexture (RtString i_fileName, RtInt i_firstChannel, RtInt i_nChannels, RtFloat i_s0, RtFloat i_t0, RtFloat i_s1, RtFloat i_t1, RtFloat i_s2, RtFloat i_t2, RtFloat i_s3, RtFloat i_t3, RtFloat *o_result, ... ): Each function takes a texture name and four input points specifying the texture region to be sampled. i_nChannels channels is retrieved starting at channel i_firstChannel in the texture i_fileName. Optional parameters (described in Table 6.15) provided as name-value pairs as accepted. All read channels are stored in o_result. These three functions also have their vector versions (RxEnvironmentV, RxShadowV and RxTextureV) which take a vector of tokens and a vector of values, similar to Ri calls. A return value of `0' indicates a sucess.

9.6.3 Space transformation function

There is a single space transformation function. It looks a lot like the transform shadeop in the shading language (Geometry, Matrices and Colors), except that it passes an array of points to transform and accepts a time parameter (useful with motion blurred geometry).

RtInt RxTransformPoints ( RtToken i_fromspace, RtToken i_tospace, RtInt i_n, RtPoint io_p[], RtFloat i_time ): The points in io_p are transformed from i_fromspace to i_tospace, at time i_time. If there is some motion blur and i_time is somewhere inside the shutter time interval, the transformation interpolates points between the two enclosing time steps. A return value of `0' means success.

9.6.4 Message passing and info functions

These functions access state and general information. They are respectively the equivalent of attribute(), option(), rendererinfo() and textureinfo() shadeops in the shading language (see section Message Passing and Information).

RtInt RxAttribute ( RtString i_name, RtPointer o_result, RtInt i_resultLen, RxInfoType_t *o_resulttype, RtInt *o_resultcount )
RtInt RxOption ( RtString i_name, RtPointer o_result, RtInt i_resultLen, RxInfoType_t *o_resulttype, RtInt *o_resultcount)
RtInt RxRendererInfo ( RtString i_name, RtPointer o_result, RtInt i_resultLen, RxInfoType_t *o_resulttype, RtInt *o_resultcount)
RtInt RxTextureInfo ( RtString i_texture, RtString i_name, RtPointer o_result, RtInt i_resultLen, RxInfoType_t *o_resulttype, RtInt *o_resultcount): The information i_name is retrieved and stored into o_result, which has a size of at least i_resultLen in bytes. The type is returned in o_resulttype and the number of base elements (of type RtString or RtFloat) contained in o_result is stored in o_resultcount. These two values may be useful for user defined attributes or options. For RxAttribute and RxOption, a return value N > 0 indicates that the call failed due to a too small buffer (N indicating the number of missing bytes). In this case, take a look at o_resulttype and o_resultcount for more explanations. A return value of 0 indicates a success. A negative return value indicates an error.

9.6.5 File functions

RtString RxCacheFile ( RtString i_filename )

This function allows access to 3Delight's network cache (see section Network Cache). When the network cache is enabled, the given file is cached and a path to the cached file is returned. If caching fails, is disabled or is not required, i_filename is returned. This function is useful when the caching of extra resources is necessary due to excessive network loads. Example resources that could benefit from caching:

Scene data. Such as Maya scene files or specific custom DSO data.

Executables. Executing files through the network is a non negligible part of the total network traffic.

Note that 3DELIGHT already caches RIB archives so caching them using this call is not a good idea.

RtString RxFindFile ( RtString i_category, RtString i_filename ): This function allows access to 3Delight's searchpath system. It will look for the requested file in the searchpaths of the given category (as given by the "searchpath" option). It will also apply any required directory mapping (see section Search Paths Options).

9.6.6 Example

Here is a simple example of a DSO using the RxTexture function. Note that the `rx.h' file is included instead of the `ri.h' file.

#include "shadeop.h"
#include "rx.h"

/*
	A simple DSO shadeop using the Rx Library

	Notes that 'extern "C"' is not necessary for '.c' files.
	Only c++ files need that.
*/

extern "C"
{
	SHADEOP_TABLE(rxTexture) =
	{
		{"color rxTexture(string, float, float, float, float, float, "
		 "float, float, float, float)", "rx_init", "rx_cleanup"},
		{""}
	};
}

extern "C" SHADEOP_INIT(rx_init)
{
	return 0x0; /* No init data */
}

extern "C" SHADEOP_CLEANUP(rx_cleanup)
{
	/* Nothing to do */
}

/*
	Given a texture file, texture coordinates and a width,
	return texture color using a gaussian filter.
	Note that the filename in argv[1] is a pointer of a string.
*/

extern "C" SHADEOP(rxTexture)
{
	RtString filter = "gaussian";
	
	return RxTexture(
		*((RtString *)argv[1]), 0, 3,
		*((RtFloat *) argv[2]), *((RtFloat *) argv[3]),
		*((RtFloat *) argv[4]), *((RtFloat *) argv[5]),
		*((RtFloat *) argv[6]), *((RtFloat *) argv[7]),
		*((RtFloat *) argv[8]), *((RtFloat *) argv[9]),
		(RtFloat *) argv[0],
		"width", (RtFloat*)argv[10],
		"filter", &filter,
		0);
}

The DSO has to be compiled with the `-shared' flag activated, as shown below for each platform:

Linux: g++ -shared -o rxexample.so -I$DELIGHT/include rxexample.cpp
IRIX: CC -shared -o rxexample.so -I$DELIGHT/include rxexample.cpp
MacOS X: g++ -dynamiclib -o rxexample.so -I$DELIGHT/include rxexample.cpp
Windows: cl -I"%DELIGHT%/include" "%DELIGHT%/lib/3delight.lib" -LD rxexample.cpp

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]