The time is passed in to functions where it is important; for example the Exec function. This argument is used to get the value of parameters at specific points in the animation, and/or to get input images at various points in the sequence.
There are several different notions of time which the programmer can get and,
in some cases, set. These are:
Global Time
Node Time Range
Parameter Time Range
Image Viewer (Flipbook) Time
These are accessed using the following calls:
Global Time CPI_Bool cpiGetGlobalFrameRange( CPI_Int32 *startFrame, CPI_Int32 *endFrame );This returns the range of frames set in the global timeline control, which is normally found at the bottom of the RAYZ interface.
Node Time CPI_Bool cpiGetInputRange( CPI_Int32 *start, CPI_Int32 *end, CPI_Uint32 whichInput );This returns the range of frames that the node sees at the given input. Inputs are numbered from 0. In those situations where you want to retrieve images other than the current one (see below), this can (and should) be called to make sure that only valid frames are requested from the cpiGetInputOp() call.
Paramter Time CPI_Bool cpiGetSequenceParmRange( CPI_Int32 *startFrame, CPI_Int32 *endFrame ); CPI_Bool cpiSetSequenceParmRange( CPI_Int32 startFrame, CPI_Int32 endFrame );These get and set the range of frames set in the parameter field of a source node, such as the Color node. Generally these values will be set by the user in a source plugin (see cpiAddSequenceRange()), such as CircleRamp.
Image Viewer and Flipbook Time CPI_Bool cpiSetImageViewerTime( CPI_Float32 curTime); CPI_Float32 cpiGetImageViewerTime( void ); CPI_Bool cpiGetFlipbookRange( CPI_Float32 *start, CPI_Float32 *end );The image viewer can have a local time that is temporarily different from the global time. This is how Track, for example, works - the overlay for the Track node gets the "Track Forward" command from the toolbar button, and uses that to request a series of frames in the current flipbook range.
CPI_ImageOp cpiGetInputOp( CPI_Uint32 input, CPI_Float32 theTime, CPI_Uint8 quality, CPI_Float32 scaleX, CPI_Float32 scaleY )The parameter 'theTime' is a value given in frames, and comes in set to the current value of global time. This is passed into the Exec function, and normally this value is simply handed on to cpiGetInputOp(). However, you can request any time (frame) you like; for example, to do time filtering around the current frame, you could do this:
static CPI_ImageOp Exec( CPI_Float32 time, CPI_Uint8 quality, CPI_Uint32 output, CPI_Bool viewerOutput, CPI_Float32 scaleX, CPI_Float32 scaleY ) { CPI_ImageOp inputs[3], retval; // request the previous frame, the current frame, and // the next frame inputs[0] = cpiGetImageOp( 0, time - 1.0F, ... ); inputs[1] = cpiGetImageOp( 0, time, ... ); inputs[2] = cpiGetImageOp( 0, time + 1.0F, ... ); // add your image op to the exec list with those 3 images as // inputs retval = cpiAddImageOp( "mytimeaverage", myParms, inputs, 3 ); }Currently, although the time is a floating point (fractional) frame number, only integer (whole) frames are returned. So time values are rounded to the nearest whole frame and that is the frame which is returned. For example, requesting frame 1.4 will return the image at frame 1; a request for frame 1.5 will return the image at frame 2.
In this case, you would use the call:
CPI_Bool NodeGetRange( CPI_Int32 *outStart, CPI_Int32 *outEnd, CPI_Uint32 output, CPI_Bool viewerOutput );And it might look something like this:
CPI_Bool NodeGetRange( CPI_Int32 *outStart, CPI_Int32 *outEnd, CPI_Uint32 output, CPI_Bool viewerOutput ) { CPI_Int32 numInputs, i, startF, endF, nframes; // find out how many inputs there are cpiGetNumInputs( &numInputs ); // for each one, get the range for ( i = 0; i < numInputs; i++ ) { cpiGetInputRange( &startF, &endF, i ); nframes = endF - startF + 1; } // set output range to 1 -> total *outStart = 1; *outEnd = nframes; return CPI_TRUE; }You would need to define a reference to the above function in the NodeInfo structure, like so:
static RPI_NodeInfo ninfo = { { "Node", // node name "node", // menu name "Silicon Grail", // author "v0.1" // version "", // help URL "" // icon name }, NodeInit, // initialize node NodeShutDown, // shut down node NULL, // parameter changed NULL, // input changed NodeGetRegion, // return result region NodeGetFullSize, // return full size NodeGetRange, // return frame range NULL, // return errors NodeExec, // node execute NULL, // input label NULL, // output label NULL, // viewer label NULL, // viewer outputs 1, // min inputs 1, // max inputs 1, // min outputs 1, // max outputs CPI_FALSE // can add more inputs }