Rx Library

Noise

Texture Lookup

3D Texture Write and Lookup

Attribute And Option State

Renderer Information

The Rx library allows writers of RiProcedural and Shading Language DSOs to query internal state of the renderer, as well as access useful internal functions which would otherwise be difficult or impossible to duplicate. In order to use these functions, the header file "rx.h" must be included with the preprocessor directive #include.

Noise

RtInt RxNoise(int inDimension, float *in,
              int outDimension, float *out);
RtInt RxPNoise(int inDimension, float *in, float *period,
               int outDimension, float *out);
RtInt RxCellNoise(int inDimension, float *in,
                  int outDimension, float *out);

These functions allows DSOs to access PRMan's internal implementation of noise, including the nonperiodic, periodic, and cellular varieties. These functions take as input an array of floats in, with dimensionality specified in inDimension (which can be 1 to 4). The output noise values is placed in out, which has dimensionality specified in outDimension. The period parameter for RxPNoise should be nonzero for periodic noise.

Texture Lookup

RtInt RxEnvironment(RtString filename, RtInt firstchannel,
                    RtInt nchannels, RtPoint dir0, RtPoint dir1, RtPoint dir2, RtPoint dir3,
                    RtFloat *result, ...);

RtInt RxShadow(RtString filename, RtInt firstchannel,
               RtPoint P0, RtPoint P1, RtPoint P2, RtPoint P3, RtFloat *result, ...);

RtInt RxTexture(RtString filename, RtInt firstchannel, RtInt nchannels,
                RtFloat s0, RtFloat t0, RtFloat s1, RtFloat t1, RtFloat s2, RtFloat t2,
                RtFloat s3, RtFloat t3, RtFloat *result, ...);

DSOs may perform filtered texture map lookups using four point versions of the corresponding shading language shadeops. Each function takes a string specifying a texture filename, four points specifying the region to be textured, and an optional parameter list. nchannels of texture data are retrieved starting at firstchannel, and stored in result. There are also corresponding vector versions (RxTextureV and so on) that take arrays of token value pairs in the same manner as other Ri calls.

A trivial example follows. The following DSO shadeop performs a 3 channel texture lookup.

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

SHADEOP_TABLE(rxtexture) =
{
    { "color rxtexture (string, float, float, float, float, float, float, float, float)", "", "" },
    { "" }
};

SHADEOP(rxtexture) {
    int status;
    int n = 1;
    float *result = (float *)argv[0];
    STRING_DESC *sd = (STRING_DESC *)(argv[n++]);
    float *s0=(float *)argv[n++], *t0=(float *)argv[n++];
    float *s1=(float *)argv[n++], *t1=(float *)argv[n++];
    float *s2=(float *)argv[n++], *t2=(float *)argv[n++];
    float *s3=(float *)argv[n++], *t3=(float *)argv[n++];

    status = RxTexture (sd->s, 0, 3,
			*s0, *t0,
			*s1, *t1,  
			*s2, *t2,
			*s3, *t3, result, 
			NULL);
    return status;
}

The resulting DSO shadeop can be invoked as follows:

surface rxtexture (string txname="")
{
    if (txname != "") {
	Ci = rxtexture(txname, s, t, s, t, s, t, s, t);
    }
    Oi = 1;
}

3D Texture Write and Lookup

RtInt RxBake3d(RtString filename, RtPoint point, RtNormal normal, RtFloat radius, ...);

RtInt RxTexture3d(RtString filename, RtPoint point, RtNormal normal, RtFloat filterradius, ...);
    

RxBake3d writes data points to a point cloud file. RxTexture3d reads texture data from a brick map file. There are also corresponding vector versions (RxBake3dV, etc) that take arrays of token value pairs in the same manner as other Ri calls.

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

SHADEOP_TABLE(dsotexture3d) =
{
    { "float dsotexture3d (string, point, normal, float)", "", "" },
    { "" }
};

SHADEOP (dsotexture3d)
{
    char bkmfilename[10] = "foo.bkm";
    float *p = (float*) argv[2];
    float *n = (float*) argv[3];
    float r = *(float*) argv[4];
    float c[3];

    RxTexture3d(bkmfilename, p, n, r, "color c", c, NULL);
    printf("color c = (%f %f %f)\n", c[0], c[1], c[2]);

    return 0;
}

    RxTexture3d(bkmfilename, p, n, r, "color c", c, "float f", f, NULL);

Attribute And Option State

int RxAttribute (const char *name, void *result, 
                 int resultlen, RxInfoType_t *resulttype, int *resultcount);

int RxOption (const char *name, void *result, int resultlen,
              RxInfoType_t *resulttype, int *resultcount);

These calls duplicate the functionality of the attribute() and option()shadeop, allowing the DSO to determine information about the current graphics state by looking up the data associated with a token-data pair in an Attribute or Option.

The name of the option or attribute to look up is passed in via name; the names that are supported include all the ones supported by the corresponding shadeop, as well as user specified attributes and options specified using the syntax user:nameofattribute.

Return values are stored in result, which should be a pointer to a contiguous chunk of memory allocated by the DSO, with size in bytes equal to resultlen. PRMan will attempt to store the results of the option or attribute call inside the storage after checking resultlen; if the storage is not large enough to store the requested attribute or option value, the Rx call will fail with nonzero status. On return, resulttype and resultcount indicate the type of data and number of items returned inside result. Checking resulttype and resultcount is particularly important for user defined attributes or options, where the type of the data may not be as expected, due to unknown RiDeclare declarations.

Note that special care must be taken when querying an attribute or option which has a value of type string. In this case, result must be a pointer to a string (char**), and the size of the string pointer (sizeof(char*)) must be passed in via resultlen. On return, *result contains the value of the string; this allocation is owned by the renderer and must not be freed.

A usage example follows. The following DSO shadeop returns a color when given a named attribute also of type color, and may be invoked by a shader using rxgetattrcolor("nameofattribute");

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

SHADEOP_TABLE(rxgetattrcolor) = {
    { "color rxgetattrcolor(string)", "", "" },
    { "" }
};

SHADEOP(rxgetattrcolor) {
    float* out = (float*)(argv[0]);
    STRING_DESC *sd = (STRING_DESC *)(argv[1]);
    RxInfoType_t type;
    int count;
    int status = RxAttribute(sd->s, out, sizeof(RtColor), 
		 &type, &count);
    if (status != 0 || type != RxInfoColor && count != 3) {
	/* The attribute did not exist - set the color to black */
	out[0] = out[1] = out[2] = 0.0f;
    }
    return status;
}

Renderer Information

int RxRendererInfo (const char *name, void *result, int resultlen, 
                    RxInfoType_t *resulttype, int *resultcount);

This call duplicates the functionality of the rendererinfo() shadeop, allowing the DSO to determine which renderer and which version it is currently running in. Much like the RxAttribute and RxOption calls, return values are stored in a contiguous memory block result of size resultlen, with resulttype and resultcount indicating the type of data and number of items returned. The following may be passed in as the value for name:

• renderer: result needs to be large enough to hold a pointer to a string (resultlen should be equal to sizeof(char*)). On return, *result contains a string containing the name of the renderer. This allocation is owned by the renderer and must not be freed. Example usage:

  char *renderer;
  status = RxRendererInfo("renderer", &renderer, sizeof(char*), 
                          &type, &count);

• version: result must be large enough to hold an array of four int (resultlen should be 4 * sizeof(int)). On return, result contains the version of the renderer. Example usage:

  int version[4];
  status = RxRendererInfo("version", &version, 4 * sizeof(int), 
                          &type, &count);
  

• versionstring: result needs to be large enough to hold a pointer to a string (resultlen should be equal to sizeof(char*)). On return, *result contains a string containing the version of the renderer as a string. This allocation is owned by the renderer and must not be freed. Example usage:

  char* versionstring;
  status = RxRendererInfo("versionstring", &versionstring, sizeof(char*), 
                          &type, &count);