appendixA.html, appendixF.html, index.html, section01.html, section02.html, section03.html, section04.html, section05.html, section06.html, section07.html, section08.html, section09.html, section10.html, section11.html, section12.html, section13.html, section14.html, section15.html, section16.html

4 - Graphics State

RiBegin( name )
     RtToken   name;
RiEnd()
    

The parameter name is used to specify which RenderDrive to use, in the form hostname or hostname:port. RenderDrive listens by default on port 5554 for rendering connections, and 5553 for control connections. The parameter is treated as a char * and need not be declared.

RI_NULL may not be used. Calls to RiOption may not be made outside of a RiBegin-RiEnd block when there is no active connection to a RenderDrive.

RiErrorHandler is valid at any time, but note that the RI_... constants are only valid inside an RiBegin-RiEnd block.

RiEnd may be called at any time to terminate the render, but must in any event be called prior to any subsequent call to RiBegin with the same instance of the RenderDrive client library.

Up to eight RenderDrives may be specified in name, separated by commas. The frames of a job are sent to each RenderDrive in sequence until all RenderDrives are in use; calls to RiFrameBegin block until a RenderDrive is free. When rendering to more than one RenderDrive, only calls to RiDeclare and RiErrorHandler may be made outside of a RiFrameBegin-RiFrameEnd block. No other synchronisation of the graphics state is performed.

EXAMPLES

     RiBegin("192.168.1.200");

     RiBegin("woolaston.art-render.com:9876");

     RiBegin("rd1, rd2, rd3, rd4");
    

RiFrameBegin( frame )
     RtInt     frame;
RiFrameEnd()
    

OK.

RiWorldBegin()
RiWorldEnd()
    

OK. At WorldEnd, all declarations made since the previous WorldBegin cease to be valid.

Options

Options marked persistent may be set such that they apply to all subsequent rendering jobs by sending a job to the RenderDrive control port.

RiFormat( xresolution, yresolution, pixelaspectratio )
     RtInt     xresolution, yresolution;
     RtFloat   pixelaspectratio;
    

RenderDrive supports images up to 16384 pixels square, less when using special camera options. pixelaspectratio is supported in the range 0.001 to 1000. When field rendering is selected with the field parameter to RiDisplay, the yresolution and pixelaspectratio are automatically halved.

Large images are split into individually-rendered tiles of under 2 million pixels. The default output handler in the client library stiches these back together.

DEFAULT

     RiFormat(640, 480, 1.0F);
    

RiFrameAspectRatio( frameaspectratio )
     RtFloat   frameaspectratio;
    

frameaspectratio takes values in the range 0.001 to 1000.

If the aspect ratio implied by RiFormat differs from the one specified to RiFrameAspectRatio then the number of pixels in the final image is changed according to the rules in the standard, which can be summarised as:

If frameaspectratio < pixelaspectratio * xresolution / yresolution then the image has yresolution*frameaspectratio / pixelaspectratio by yresolution pixels.

If frameaspectratio > pixelaspectratio * xresolution / yresolution then the image has xresolution by xresolution*pixelaspectratio / frameaspectratio pixels.

In other words, the image is always decreased in one direction to the specified frameaspectratio.

RiScreenWindow( left, right, bottom, top )
     RtFloat   left, right, bottom, top;
    

Selects the window on the image plane that is rendered. The angle between -1 and 1 in a direction is defined by the "fov" parameter to RiProjection.

The default screen window has the same aspect ratio as the output frame, and contains the square [-1 1 -1 1] in the image plane.

RiCropWindow( xmin, xmax, ymin, ymax )
     RtFloat   xmin, xmax, ymin, ymax;
    

The file returned to the client will be of the crop size, and contain an offset to its position in the full-size image. The default output handler in the client library will process it so that the rendition file is always of the full size determined by RiFormat, RiFrameAspectRatio, etc. The cropped section will have an unrendered border around it, or, if the file exists already, the cropped section will be stitched into it.

RiProjection( name, parameterlist )
     RtToken   name;
    

Of the standard projections, RenderDrive supports RI_PERSPECTIVE and RI_ORTHOGRAPHIC, which are always appended to an identity transformation (rather than the current transformation). RI_NULL may not be used to specify an arbitrary camera space.

The orthographic projection optionally performs an arbitrary step forward to the scene bounding box before the start of rendering, controlled by:

      RiOption(RI_RENDER, RI_ORTHOGRAPHICSTEPFORWARD, boolean)
      

DEFAULT

     RiProjection(RI_PERSPECTIVE, RI_FOV, 90, RI_NULL);
    

RiClipping( near, far )
     RtFloat   near, far;
    

RenderDrive clips objects to the near and far clipping planes in terms of primary visibility. Objects the wrong side of these planes are still visible to rays generated from trace() and still cast shadows.

By default, RenderDrive scales depth values as specified in the RenderMan standard, but raw Z values can be supplied instead. The raw values give z=far where no object is in line of sight.

DEFAULT

     RtToken tokens[1];
     RtPointer values[1];
     RtString strarr[1];
     tokens[0] = RI_DEPTH;
     values[0] = (RtPointer) strarr;
     strarr[0] = "screen"; /* Scale depth to clipping planes */
     RiOptionV(RI_RENDER, 1, tokens, values);
     RiClipping(RI_EPSILON, RI_INFINITY);

EXAMPLE

     /* set up variables as above */
     strarr[0] = "world"; /* Do not scale depth values */
     RiOptionV(RI_RENDER, 1, tokens, values);
    

RiDepthOfField( fstop, focallength, focaldistance )
     RtFloat   fstop;
     RtFloat   focallength;
     RtFloat   focaldistance;
    

OK.

DEFAULT

     RiDepthOfField(RI_INFINITY, 1.0F, 1.0F);
    

RiShutter( min, max )
     RtFloat   min, max;
    

OK.

DEFAULT

     RiShutter(0.0F, 0.0F); /* No motion blur */
    

RiPixelVariance( variation )
     RtFloat   variation;
    

Overrides any previous use of RiPixelSamples except RiPixelSamples(0, 0) or RiOption(RI_RENDER, RI_QUALITY), see below, and sets the RenderDrive to use variance-based adaptive sampling, which is the default rendering mode.

A PixelVariance of 1 will generate a preview image based on just one sample per four pixels.

Although RiPixelVariance can be used to control the RenderDrive adaptive sampler it is recommended that it is controlled instead through the RiOption mechanism for setting a rendering quality value:

      RtFloat quality = 75.0;
      RiOption(RI_RENDER, RI_QUALITY, &quality);
    

Quality 0.0 results in a rapid preview image as in RiPixelVariance(1.0). Quality 100.0 generates a high-quality image. Qualities in the range 50 to 100 are expected to be adequate for most images, but for some still frames quality values over 100 might be necessary.

DEFAULT

     RiPixelVariance(0.03125);
    

RiPixelSamples( xsamples, ysamples )
     RtFloat   xsamples, ysamples;
    

Persistent

Overrides any previous use of RiPixelVariance or RiOption(RI_RENDER, RI_QUALITY), setting the RenderDrive to trace a fixed number of eye-rays per pixel. RenderDrive allows a special sampling rate of 0, which forces the use of exactly 1 sample per pixel even in the face of a subsequent calls which would otherwise invoke the adaptive sampler.

It is not possible to control the amounts of sampling in the x and y directions independently. Instead, the multiple of xsamples and ysamples is used to give the number of samples to take per pixel.

DEFAULT

     RiPixelSamples(2,2); 
    

RiPixelFilter( filterfunc, xwidth, ywidth )
     RtFloatFunc       filterfunc;
     RtFloat   xwidth, ywidth;
    

RenderDrive supports the five standard filter functions, RiBoxFilter, RiTrangleFilter, RiCatmullRomfilter, RiGaussianFilter, and RiSincFilter, and the two PRMan 3.7 extensions, RiBesselFilter and RiDiskFilter. Used-defined filter functions are not supported in this release.

DEFAULT

     RiPixelFilter(RiBoxFilter, 1.4F, 1.4F);
    

RiExposure( gain, gamma )
     RtFloat   gain;
     RtFloat   gamma;
    

Persistent

Exposure correction is only applied to quantised RGB channels, which in particular means no gain is applied to floating-point RGB data.

DEFAULT

     RiExposure(1.0F, 2.2F);
    

RiImager( name, parameterlist )
     RtToken   name;
    

Imager shaders are not supported.

DEFAULT

     RiImager(RI_NULL_IMAGER_SHADER);
    

RiQuantize( type, one, min, max, ditheramplitude )
     RtToken   type;
     RtInt     one, min, max;
     RtFloat   ditheramplitude;
    

Persistent

The depth and colour quantisers in force at RiWorldEnd are applied to all appropriate RiDisplay calls in force for that world unless overriden by explicit quantize and dither parameters to the individual display call.

type can be RI_RGBA or RI_Z.

RenderDrive's quantisers support only 8 and 16 bit quantised integer output, together with 32 bit floating point which is specified by one=0.0.

DEFAULT

     RiQuantize(RI_RGBA, 65535, 0, 65535, 256.0F);
     RiQuantize(RI_Z, 0, 0, 0, 0.0F);
    

RiDisplay( name, type, mode, parameterlist )
     char       *name;
     RtToken   type;
     RtToken   mode;
    

RenderDrive allows for rendering several output files per world, using a syntax similar to PRMan 3.8. However, only known channels can be rendered; arbitrary shader output values are not supported.

After the first call to RiDisplay, all subsequent calls should prepend a "+" to the front of the name. Calling RiDisplay with a name that does not begin with "+" clears all previous calls and begins the display specification again.

Channels with the same output bit depth after quantisation may specify the same image name (with a prepended "+") up to a maximum of 16 channels per image file.

If the quantisation settings for a channel prevent it from being output in the same file as other channels of the same name, it is output in a seperate file with the first letter of the "mode" appended as an extension to the filename. Potentially, other channels with matching filename an quantisation settings may be added too, contributing another letter to the extension.

RGB (and RGB only) may be specified more than once, with different quantisation or exposure parameters on each call. One of the calls may be RGBA, RGBZ or RGBAZ. If unquantised data is required, it must be the first RGB channel requested.

Type is currently ignored, except that it must be a declared or standard token, and every secondary call to RiDisplay must match the type of the primary. RI_FILE and RI_FRAMEBUFFER are both available for use.

Mode must be a declared or standard token. In addition to the standard modes RI_RGB, RI_A, RI_Z, RI_RGBA, RI_RGBAZ, RI_AZ, RI_RGBZ, RenderDrive supports the following extra channels:

If requested, ID1 and ID2 are filled respectively with the value of the shader parameters ID1 and ID2 (as specified to RiSurface) on the frontmost surface.

Parameters applicable to RenderDrive RiDisplay calls:

The elements of "quantize" are respectively zero, one, min and max.

"field" 0 turns off field rendering, "field" 1 or 2 selects either odd or even numbered fields as appropriate, where the lines are numbered from 1, the top line of the image. When field rendering is selected, the output image is half the height specified by RiFormat, and the pixelAspect ratio is halved to match.

Preview images delivered when using the "preview" parameter are selfcontained TIFF or PNG images showing only the updated portion, with position information to allow for stitching into place. However, the whole tile is always delivered once at the end of rendering.

EXAMPLE

     RtInt preview = 0;
     RtInt noquant[4] = { 0, 0, 0, 0 };
     RtInt idquant[4] = { 0, 1, 0, 65535 };
     RtFloat dither = 0;
     RtToken tokens[3];
     RtPointer values[3];

     tokens[0] = RI_PREVIEW;
     tokens[1] = RI_QUANTISE;
     tokens[2] = RI_DITHER;

     /* Unquantised floating point RGB */
     values[0] = (RtPointer)&preview;
     values[1] = (RtPointer)&noquant;
     values[2] = (RtPointer)&dither;
     RiDisplayV("float.tiff", RI_FILE, RI_RGB, 3, tokens, values);

     /* 16-bit integer node ID */
     values[1] = (RtPointer)&idquant;
     RiDisplayV("+IDs.tiff", RI_FILE, RI_ID1, 3, tokens, values);

     /* Don't need quantize or dither override on remainder */
     RiDisplayV("+normal.tiff", RI_FILE, RI_N, 1, tokens, values);

     /* Use progressive update on quantized image only */
     preview = 1;
     RiDisplayV("+image.tiff", RI_FILE, RI_RGBAZ, 1, tokens, values);
    

RiHider( type, parameterlist )
     RtToken   type;
    

RenderDrive supports the hiders RI_HIDDEN and RI_NULL. RI_PAINT is not supported.

DEFAULT

     RiHiderV(RI_HIDDEN, 0, NULL, NULL);
    

RiColorSamples( n, nRGB, RGBn )
     RtInt     n;
     RtFloat   nRGB[], RGBn[];
    

Not implemented.

RiRelativeDetail( relativedetail )
     RtFloat   relativedetail;
    

Not implemented.

RiOption( name, parameterlist )
     RtToken   name;
    

The options that can be set with this call are shown in the table below.

* persistent

Attributes

RiAttributeBegin()
RiAttributeEnd()
    

OK.

RiColor( color )
     RtColor   color;
    

OK.

DEFAULT

     RtColor white = { 1.0F, 1.0F, 1.0F };
     RiColor(white);
    

RiOpacity( color )
     RtColor   color;
    

OK.

DEFAULT

     RtColor white = { 1.0F, 1.0F, 1.0F };
     RiOpacity(white);
    

RiTextureCoordinates( s1,t1,s2,t2,s3,t3,s4,t4 )
     RtFloat   s1, t1;
     RtFloat   s2, t2;
     RtFloat   s3, t3;
     RtFloat   s4, t4;
    

OK.

RtLightHandle
     RiLightSource( shadername, parameterlist )
     RtToken   shadername;
    

The four standard light source shaders are provided.

No light source may be defined outside a World block.

The parameter shadername should not be declared, and is treated as a char *. RenderDrive light source shader names are declared and indexed automatically within a unique namespace for light sources.

RtLightHandle
     RiAreaLightSource( shadername, parameterlist )
     RtToken   shadername;
    

Partially implemented.

Calls to RiAreaLightSource cause light to be emitted from a cuboidal volume, defined to be the axis-aligned bounding box (in the coordinate system in force at the time of the RiAreaLightSource call) of all the geometry between the call and the next AttributeEnd. Note that this differs from the surface-based area light implied by the Specification since light rays are generated from all points within this volume, not just its surface.

RiIlluminate( light, onoff )
     RtLightHandle     light;
     RtBoolean onoff;
    

It is not possible to turn off ambient lights, or ambient components of light source shaders.

RiLightFree( light, onoff )
     RtLightHandle     light;
    

Not supported. (RenderDotC extension)

RiSurface( shadername, parameterlist )
     RtToken   shadername;
    

A call to RiSurface sets the current surface shader to shadername. RenderDrive currently only applies one shader per geometric primitive. See Section 9 for details on which is chosen if more than one are specified.

The six standard surface shaders "constant", "matte", "metal", "plastic", "paintedplastic" and "shinymetal" are provided. In addition, a ray-traced version of "shinymetal" is provided, called "tracedmetal". It lacks the parameter texturename since the reflections are ray-traced.

The parameter shadername should not be declared, and is treated as a char *. RenderDrive surface shader names are declared automatically within a unique namespace for surface shaders.

RiAtmosphere( shadername, parameterlist )
     RtToken   shadername;
    

RenderDrive only allows one atmosphere shader per world. The last one declared, irrespective of state, will be the one used.

The parameter shadername should not be declared, and is treated as a char *. RenderDrive atmosphere shader names are declared automatically within a unique namespace for volume shaders (i.e., atmosphere and interior shaders).

RiInterior( shadername, parameterlist );
      RtToken  shadername;
    

A call to RiInterior sets the current interior shader to shadername. RenderDrive currently only applies one shader per geometric primitive. See Section 9 for details on which is chosen if more than one are specified.

In the current RenderDrive implementation, RiInterior may be applied to any geometry, regardless of whether it has been enclosed in an RiSolidBegin-RiSolidEnd block.

The parameter shadername should not be declared, and is treated as a char *. RenderDrive atmosphere shader names are declared automatically within a unique namespace for volume shaders (i.e., atmosphere and interior shaders).

RiExterior( shadername, parameterlist );
     RtToken   shadername;
    

Not implemented.

RiShadingRate( size )
     RtFloat   size;
    

Has no effect.

RiShadingInterpolation( type )
     RtToken   type;
    

Not implemented.

RiMatte( onoff )
     RtBoolean onoff;
    

Not implemented.

RiBound( bound )
     RtBound   bound;
    

This call has no effect.

RiDetail( bound )
     RtBound   bound;
    

Not implemented. 'Level Of Detail' not supported.

RiDetailRange( minvisible, lowertransition, uppertransition, maxvisible )
     RtFloat   minvisible, lowertransition;
     RtFloat   uppertransition, maxvisible;
    

Not implemented. 'Level Of Detail' not supported.

RiGeometricApproximation( type, value )
     RtToken   type;
     RtFloat   value;
    

RenderDrive automatically simplifies overtessellated geometry, controlled through the "edgelength" RiGeometricApproximation type.

The value provides the threshold for the detessellation: to a first approximation triangles whose largest extent is larger than that number of pixels will be preserved, whereas smaller triangles may be eliminated or combined. Setting value to 0.0 will turn off detessellation.

Previous versions of the software used the "flatness" type for this purpose. This is still supported for backwards compatability, but will cease to be at some point in the future.

DEFAULT
     RiGeometricApproximation(RI_EDGELENGTH, 0.5F);
    

RiOrientation( orientation )
     RtToken   orientation;
    

OK.

RiReverseOrientation()
    

OK.

RiSides( sides )
     RtInt     sides;
    

OK.

Transformations

RiIdentity()
    

OK.

RiTransform( transform )
     RtMatrix  transform;
    

OK.

RiConcatTransform( transform )
     RtMatrix  transform;
    

OK.

RiPerspective( fov )
     RtFloat   fov;
    

OK.

RiTranslate( dx, dy, dz )
     RtFloat   dx, dy, dz;
    

OK.

RiRotate( angle, dx, dy, dz )
     RtFloat   angle;
     RtFloat   dx, dy, dz;
    

OK.

RiScale( sx, sy, sz )
     RtFloat   sx, sy, sz;
    

OK.

RiSkew( angle, dx1, dy1, dz1, dx2, dy2, dz2 )
     RtFloat   angle;
     RtFloat   dx1, dy1, dz1;
     RtFloat   dx2, dy2, dz2;
    

OK.

RiDeformation( shadername, parameterlist )
     RtToken   shadername;
    

Transformation shaders are not supported currently (except as camera shaders see RiProjection ).

RiDisplacement( shadername, parameterlist )
     RtToken   shadername;
    

Displacement shaders are supported.

RiCoordinateSystem( space )
     RtToken   space;
    

OK. Coordinate systems do not need to be predeclared.

RtPoint *
RiTransformPoints( fromspace, tospace, n, points )
     RtToken   fromspace, tospace;
     RtInt     n;
     RtPoint   points[];
    

Not implemented.

RiCoordSysTransform( space )
     RtToken   space;
    

RiTransformBegin()

RiTransformEnd()
    

OK.

Implementation-specific Attributes

RiAttribute( name, parameterlist );
     RtToken   name;
    

Attributes that can be set with this call are:

Last modified: Mon Jul 14 20:56:28 2003