TeraRecon, Inc.
Real Time Visualization

June-15-2001
=============================================================



Usage of Threaded Render Library

The VLI 2.1 release contains a header file, VLIThreaded.h, to allow the application to launch a 
volume render in a separate thread and abort that render as needed.

The application must:
#include vli.h
#include VLIThreadedRender.h

The application must be linked against the threaded render library as in this example:
CC -O -o testthread testthread.cpp xglwin.o -llibvli -lGLU -lGL -lXext -lX11 -lm lpthread

Under IRIX, the threaded library is libvlit.  Please note that the threaded rendering library is not 
supported under HP-UX.  Under Win32, the VLI libraries are compiled against the threaded 
libraries.

The following are code snippets to show the usage of the threaded render library.  These are 
presented in order of operation.

1) The application must declare and initialize a number objects as follows:
VLIPixel *baseplane = NULL;
VLIVolume *volume = NULL;
VLIContext *context = NULL;
VLIThreadedRender *vliTR = new VLIThreadedRender;
VLIVector3D hexagon[6];
VLIVector2D textureCoords[6];
int bpWidth = 0;
int bpHeight = 0;
int imageWidth = 0;
int imageHeight = 0;
unsigned int XVolSize = 0;
unsigned int YVolSize = 0;
unsigned int ZVolSize = 0;
double dRotationAngle = 0.0;

2) The application must initialize the VLI:
// Open VLI
VLIStatus status = VLIOpen();

// Create a volume from a file
volume = VLIVolume::CreateFromFile (path/to/vox/file);

// Create a context with all parameters defaulted
context = VLIContext::Create();

// Get the Size of the Volume.
volume->GetSize(XVolSize, YVolSize, ZVolSize);

// Set up the Model matrix.
VLIMatrix CorrectionMatrix = volume->GetModelMatrix();
volume->SetModelMatrix (CorrectionMatrix *VLIMatrix::Translate (-0.5 * XVolSize, -0.5 * 
YVolSize, -0.5 * ZVolSize)); 

3) The View matrix must be set up.
// Set up the View  matrix.
VLIVector3D oVLIVector3D(0.5,1.0,0.0);
context->GetCamera().SetViewMatrix(VLIMatrix::Rotate (dRotationAngle,oVLIVector3D));

4) The application is now ready to render the volume.  Instead of calling 
VLIContext::RenderBasePlane, the application calls VLIThreadedRender::Render.
//Issue render check
VLIStatus st = vliTR->Render_Check (context, volume, 0);
if (st == kVLIOK)
{
    //Issue render command
    vliTR->Render (context, volume, 0);
}

5) The application can now check to see if the render is complete.
if( vliTR-> IsRenderDone(context,0))
    // Render complete
else
    // Render in progress

6) Once the render is complete, the application will fetch the base plane and release it.
// Get the base plane
VLIStatus st = vliTR->Fetch (context, 0, bpWidth, bpHeight, imageWidth, 
                                               imageHeight, baseplane,
                                               hexagon, textureCoords);
// Release the base plane
vliTR->Release (context, 0);

7) To clean up, the application must release the context and the volume and close the VLI.
context->Release();
volume->Release();
delete vliTR;
VLIClose();

8) At any time during render processing, the application may abort the render as follows:
// Check if render is still in progress
if ( ! vliTR-> IsRenderDone(context, 0))	// if NOT YET DONE
{
    // Attempt the abort
    VLIStatus st = vliTR->Abort (context, 0);
          
    // If successful, release the base plane
    if (st == kVLIErrAborted)
        vliTR->Release (context, 0);
}