Handling Time in RAYZ

What Time Is It?

In RAYZ, the concept of "time" is handled as a floating point number which represents a frame. Fractional frames are permitted, but whenever one is used, it is first rounded to the nearest integer.

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.

Requesting Different Times

Nodes which take inputs get access to those input images with the call
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.

Changing the Output Range

There is a function call that you can define which will return the resulting frame range from your node. In most cases, the output range will be the same as the input range. However, your node may change that, for example if you wrote a version of the Sequence node, which concatenated several sequences together.

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
}

[Previous Page] [Next Page]
[Table of Contents] [Index]

Copyright © 2002 Silicon Grail Inc.
736 Seward Street, Hollywood, CA 90038