DirectTrace  0.9
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
DTRayBuffer Class Reference

DTRayBuffer Class class provides tools related to handling Sets of Rays. More...

#include <DirectTraceAPI.h>

+ Inheritance diagram for DTRayBuffer:
+ Collaboration diagram for DTRayBuffer:

List of all members.

Public Member Functions

 DTRayBuffer (DirectTraceAPI &api)
 ~DTRayBuffer ()
void operator= (DTRayBuffer &rays)
void operator+= (DTRayBuffer &rays)
void operator-= (DTRayBuffer &rays)
void operator*= (DTRayBuffer &rays)
void operator*= (float c)
DTHandle Centers ()
 This function returns a handle to an image storing the centers of the rays inside the ray buffer.
DTHandle Directions ()
 This function returns a handle to an image storing the directions of the rays inside the ray buffer.
void GenerateRandomLocationsAndDirections (DTScene &scene)
void GenerateRandomRays (float *boundingBox)
bool GetCLShaderState (int shaderId)
 This function indicates whether a given shader has previously been loaded or not.
void GetElement (int nb, float *center, float *direction)
 Gets the value of the nb-th active ray in the buffer.
void GetElement (DTImage &source, int nb, float *vector)
 Gets the value of a vector element of a 2D image linked to the nb-th active ray in the buffer.
int GetNbOfActiveRays ()
 This function returns the number of active rays inside a RayBuffer.
void GetNormalsAtIntersections (DTScene &scene, DTRayBuffer &rays, int interpolation)
int GetSize (int dim)
 Returns the size of the buffer matrix on dimension dim.
void GetZBuffer ()
void SetZBuffer ()
void GLDisplay (float scale=1.f)
 A function that makes GL calls to display the location and possibly direction of each active ray.
void MergeWith (DTRayBuffer &rays)
 This function adds the active rays of the buffer passed as parameter to the current ray buffer. This call changes the particular ray-ordering of the buffer and may resize the buffer if needed. Information about non active rays will be lost.
void MergeWith (DTRayBuffer &rays, DTHandle *destProperties[], DTHandle *sourceProperties[])
void MoveRaysToIntersections (float epsilon=-0.000002f)
 Deprecated. This function moves the centers of the active rays to the intersection coordinates.
void Normalize ()
 This function normalizes the directions of the rays inside a ray buffer.
void Resize (int x, int y)
 This function resizes a 2D matrix of rays and allocates memory accordingly.
void RunCL (int shaderId, int queue=0)
 This function executes a shader previously loaded with SetCL, and parameters specified by SetCLParam. correspond to the one specified when the material has been created.
void Run (int(*shader)(void *matAttrib, void *primAttrib, float *[]), DTHandle *argImageV[], int nbRootArguments=0)
void Run (int(*shader)(float *[]), DTHandle *argImageV[], int nbRootArguments=0)
int SetSimplifiedCL (int shaderId, char *openCLShaderCode, char *compilationOptions, int extraArgs)
int SetCL (int shaderId, char *openCLShaderCode, char *compilationOptions, int extraArgs)
 This function set up an OpenCL shader running on an OpenCL 1.0 compliant device. The shader is executed for all the active rays of the RayBuffer object. Behavior for inactive rays is undefined.
void SetCLQueue (int queue)
 This function sets the OpenCL queue used for subsequent shader calls.
int SetCLParam (int shaderId, int param, void *elem, int size=sizeof(void *))
 This function specifies an independant parameter prior to a call to RunCL.
int SetCLParam (int shaderId, int param, DTImage &handle, bool read=true, bool write=true)
 This function specifies a non-independant parameter prior to a call to RunCL.
int SetCLParam (int shaderId, int param, DTHandle h, bool read=true, bool write=true)
int SetCLParam (int shaderId, int param, int samplerParam, DTTexture &handle, bool read=true, bool write=false)
int SetCLParam (int shaderId, int param, DTTexture &handle, bool read=true, bool write=false)
void SetFrustumRaysFromGLProjectionMatrix ()
 Generates frustum ray coordinates from the OpenGL projection matrix.
void SetFrustumRaysFromPyramidF (float *center, float *corners[4], SUBCOPY_STYLE layout=SUBCOPY_NONE, int layoutId=0)
 Generates frustum ray coordinates from a pyramid described from a 3D center and four corner 3D coordinates.
void SetRays4D (int nbRays, float *pos, float *dir)
 Transfers (linearly) nbRays from user arrays to a RayBuffer object.
void SetRandomlyDisplacedFrustumRaysFromPyramidF (float *center, float *corners[4], SUBCOPY_STYLE layout=SUBCOPY_NONE, int layoutId=0)
 Generates frustum ray coordinates from a pyramid described from a 3D center and four corner 3D coordinates. Locations of rays inside the pixel are uniformly shifted on x and y by a random value not exceeding the size of one pixel.
void Shuffle ()
 Shuffle the active rays inside a ray buffer.
void Shuffle (DTHandle *argHandleV[])
void Touch (COHERENCY_TYPE rayType=FULLY_INCOHERENT_RAYS)
 This function must be called prior to a call to Intersector() when RayBuffer positions and directions have been modified by a call to a shader function.
void CopyPositions (DTRayBuffer &source)
void CopyDirections (DTRayBuffer &source)
DTHandle PrimitiveTypes ()
DTHandle Primitives ()
void GenerateHemisphericalRandomDirections (DTRayBuffer &normals, int randomizationType)
- Public Member Functions inherited from DTHandle
void operator= (DTHandle &h)
DT_HANDLE GetHandle ()
void SetHandle (DT_HANDLE h)
DT_HANDLE_TYPE GetHandleType ()
void SetHandleType (DT_HANDLE_TYPE ht)
 DTHandle (DirectTraceAPI &api, DT_HANDLE_TYPE type)
 DTHandle (DTHandle *parent)
 DTHandle (DTHandle &parent)
 ~DTHandle ()

Additional Inherited Members

- Protected Attributes inherited from DTHandle
DT_HANDLE_TYPE htype
DT_HANDLE handle
DirectTraceAPIdtAPI
bool clone

Detailed Description

DTRayBuffer Class class provides tools related to handling Sets of Rays.

Definition at line 476 of file DirectTraceAPI.h.


Constructor & Destructor Documentation

DTRayBuffer::DTRayBuffer ( DirectTraceAPI api)

Definition at line 252 of file DirectTraceAPI.cpp.

DTRayBuffer::~DTRayBuffer ( )

Definition at line 253 of file DirectTraceAPI.cpp.


Member Function Documentation

DTHandle DTRayBuffer::Centers ( )

This function returns a handle to an image storing the centers of the rays inside the ray buffer.

Returns:
A Handle.

Use

The handle will be used to specify and modify centers of the rays when running shaders.

Note

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Run
RunCL
SetCLParam

Definition at line 254 of file DirectTraceAPI.cpp.

void DTRayBuffer::CopyDirections ( DTRayBuffer source)
void DTRayBuffer::CopyPositions ( DTRayBuffer source)
DTHandle DTRayBuffer::Directions ( )

This function returns a handle to an image storing the directions of the rays inside the ray buffer.

Returns:
A Handle.

Use

The handle will be used to specify and modify directions of the rays when running shaders.

Note

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Run
RunCL
SetCLParam

Definition at line 255 of file DirectTraceAPI.cpp.

void DTRayBuffer::GenerateHemisphericalRandomDirections ( DTRayBuffer normals,
int  randomizationType 
)

Definition at line 265 of file DirectTraceAPI.cpp.

void DTRayBuffer::GenerateRandomLocationsAndDirections ( DTScene scene)
void DTRayBuffer::GenerateRandomRays ( float *  boundingBox)

Definition at line 273 of file DirectTraceAPI.cpp.

bool DTRayBuffer::GetCLShaderState ( int  shaderId)

This function indicates whether a given shader has previously been loaded or not.

Parameters:
shadereIdId of the shader to be tested.
Returns:
True if the shader has previously been loaded.

Use

In conjunction and prior to a call to SetCL and RunCL, to test if a specific shader must be loaded first before execution.

Note

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
GetCLShaderState
SetCL
RunCL
GetCLShaderState

Definition at line 335 of file DirectTraceAPI.cpp.

void DTRayBuffer::GetElement ( int  nb,
float *  center,
float *  direction 
)

Gets the value of the nb-th active ray in the buffer.

Parameters:
nbActive ray Number
centerA 4D float array pointer where the data will be copied.
directionA 4D float array pointer where the data will be copied.
Returns:

Use

Retreving positions and directions for photons, etc...

Note

There may be performance issues when calling this function.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
GetNbOfActiveRays

Definition at line 270 of file DirectTraceAPI.cpp.

void DTRayBuffer::GetElement ( DTImage source,
int  nb,
float *  vector 
)

Gets the value of a vector element of a 2D image linked to the nb-th active ray in the buffer.

Parameters:
sourceAn image buffer containing extra information.
nbActive ray Number
centerA 4D float array pointer where the data will be copied.
directionA 4D float array pointer where the data will be copied.
Returns:

Use

Retreving extra information associated with rays. like colors at intersections, etc...

Note

There may be performance issues when calling this function.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
GetNbOfActiveRays

Definition at line 271 of file DirectTraceAPI.cpp.

int DTRayBuffer::GetNbOfActiveRays ( )

This function returns the number of active rays inside a RayBuffer.

Returns:
A 32-bit integer.

Use

Note

Compatibility

Supported by OpenCL versions of DirectTrace.

Definition at line 258 of file DirectTraceAPI.cpp.

void DTRayBuffer::GetNormalsAtIntersections ( DTScene scene,
DTRayBuffer rays,
int  interpolation 
)

Definition at line 264 of file DirectTraceAPI.cpp.

int DTRayBuffer::GetSize ( int  dim)

Returns the size of the buffer matrix on dimension dim.

Parameters:
dimThe dimension concerned.
Returns:
Size on x or y.

Use

Note

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:

Definition at line 338 of file DirectTraceAPI.cpp.

void DTRayBuffer::GetZBuffer ( )
void DTRayBuffer::GLDisplay ( float  scale = 1.f)

A function that makes GL calls to display the location and possibly direction of each active ray.

Parameters:
scaleA scaling value.
Returns:

Use

Visual debugging of rays

Note

The specifications of this function may change with time.

Compatibility

Supported by OpenCL versions of DirectTrace.

Definition at line 267 of file DirectTraceAPI.cpp.

void DTRayBuffer::MergeWith ( DTRayBuffer rays)

This function adds the active rays of the buffer passed as parameter to the current ray buffer. This call changes the particular ray-ordering of the buffer and may resize the buffer if needed. Information about non active rays will be lost.

Parameters:
raysrays that will be added to the current buffer.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
MergeWith

Definition at line 268 of file DirectTraceAPI.cpp.

void DTRayBuffer::MergeWith ( DTRayBuffer rays,
DTHandle destProperties[],
DTHandle sourceProperties[] 
)

Definition at line 273 of file DirectTraceAPI.cpp.

void DTRayBuffer::MoveRaysToIntersections ( float  epsilon = -0.000002f)

Deprecated. This function moves the centers of the active rays to the intersection coordinates.

Parameters:
epsilonAn epsilon value that can be used to specify whether the centers should be located slighly before or after the real intersection. This is to prevent self intersections in future calls to Intersector().
Returns:

Use

After a call to Intersector(), where the intersections are determined.

Note

It might be more efficient to carry out the operation along other operations with a shader from the t values, centers and directions of rays.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Intersector
Run
RunCL

Definition at line 263 of file DirectTraceAPI.cpp.

void DTRayBuffer::Normalize ( )

This function normalizes the directions of the rays inside a ray buffer.

Returns:

Use

Note

Compatibility

Supported by OpenCL versions of DirectTrace.

Definition at line 262 of file DirectTraceAPI.cpp.

void DTRayBuffer::operator*= ( DTRayBuffer rays)
void DTRayBuffer::operator*= ( float  c)
void DTRayBuffer::operator+= ( DTRayBuffer rays)
void DTRayBuffer::operator-= ( DTRayBuffer rays)
void DTRayBuffer::operator= ( DTRayBuffer rays)

Definition at line 257 of file DirectTraceAPI.cpp.

DTHandle DTRayBuffer::Primitives ( )
DTHandle DTRayBuffer::PrimitiveTypes ( )

Definition at line 256 of file DirectTraceAPI.cpp.

void DTRayBuffer::Resize ( int  x,
int  y 
)

This function resizes a 2D matrix of rays and allocates memory accordingly.

This function resizes a 2D image.

Parameters:
xDimension on x
yDimension on y
Returns:
A boolean indicating whether the allocation has been succesful or not.

Use

Note

Return value may not be accurate in early implementations. Allocation of memory on OpenCL devices may be delayed after the call. Dimensions should be a multiple of 8 for best results.

See also:
SetFrustumRaysFromPyramidF

Compatibility

Supported by OpenCL versions of DirectTrace.

Parameters:
xDimension on x
yDimension on y
nbComponentsComponents per pixel
complexModeUse of complex numubers. Check support for complex numbers.
Returns:
A boolean indicating whether the allocation has been succesful or not.

Use

Note

Components are 32-bit values, which can be interpreted as floats or integers according to the needs. Return value may not be accurate in early implementations. Allocation of memory on OpenCL devices may be delayed after the call. Dimensions should be a multiple of 8 for best results.

Compatibility

Supported by OpenCL versions of DirectTrace.

Definition at line 261 of file DirectTraceAPI.cpp.

void DTRayBuffer::Run ( int(*)(void *matAttrib, void *primAttrib, float *[])  shader,
DTHandle argImageV[],
int  nbRootArguments = 0 
)
void DTRayBuffer::Run ( int(*)(float *[])  shader,
DTHandle argImageV[],
int  nbRootArguments = 0 
)
void DTRayBuffer::RunCL ( int  shaderId,
int  queue = 0 
)

This function executes a shader previously loaded with SetCL, and parameters specified by SetCLParam. correspond to the one specified when the material has been created.

Parameters:
shadereIdId of the shader to be tested.
Returns:
void

Use

Note

Note that shaders will run only on data/pixels related to active rays. For non-active rays, it may be suitable to initialize their related pixel data before, as autmoatic transfers of data between CPU/GPU may fail. See section dedicated to shaders. If you modify ray coordinates in shaders, you will need to make a call to Touch() right after the shader and to make sure you have setup the t value (usually MAXFLOAT) as well. See section dedicated to shaders.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
GetCLShaderState
SetCL
RunCL
GetCLShaderState
Touch

Definition at line 337 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetCL ( int  shaderId,
char *  openCLShaderCode,
char *  compilationOptions,
int  extraArgs 
)

This function set up an OpenCL shader running on an OpenCL 1.0 compliant device. The shader is executed for all the active rays of the RayBuffer object. Behavior for inactive rays is undefined.

Parameters:
shaderIdIndicates a shader id for the specific variable. This number should be in the range [0..MaxShadersPerObject-1].
openCLShaderCodeString describing the OpenCL program. The function must follow a specific signature. See the specific sections on using shaders.
compilationOptionsString describing additional compilations options.
extraArgsNumber of arguments that dot not have a 1 to 1 pixel correspondance. These arguments can be int, floats, or general 32-bit arrays with global indexing. They will be the last parameters specified in the function header.
Returns:
A boolean indicating whether the operation has been succesful or not.

Use

Note

Inlike DTImage shaders, the shader function should return a boolean indicating whether a specific ray should remain active or not.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
RunCL
SetCLParam
RunCL
GetCLShaderState

Definition at line 328 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetCLParam ( int  shaderId,
int  param,
void *  elem,
int  size = sizeof (void *) 
)

This function specifies an independant parameter prior to a call to RunCL.

Parameters:
shaderIdSpecify the shader to be executed. This value must have been specified first to the SetCL function.
paramid of the param. Param starts from 2.
elemPointer to the object passes as paramter. This includes any kind of objects that can be passed to an OpenCL kernel 1.0, including parameters like int, float, array of 4 floats, cl_mem, texture objects, etc...
sizesize of the object passed as parameter.
Returns:
an int indicating whether the call was succesfull or not.

Use

Using extra parameters to add flexibility to shaders.

Note

There must be as many calls to this function as the number of independant parameters specified previously with a call to SetCL. See the use of shaders the dedicated sections.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
GetCLShaderState
SetCL
RunCL
GetCLShaderState

Definition at line 330 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetCLParam ( int  shaderId,
int  param,
DTImage handle,
bool  read = true,
bool  write = true 
)

This function specifies a non-independant parameter prior to a call to RunCL.

Parameters:
shaderIdSpecify the shader to be executed. This value must have been specified first to the SetCL function.
paramid of the param. Param starts from 2.
handleAn image containing additional Information on a per pixel basis.
readA boolean value indicating if the image is data going to be read by the shader.
readA boolean value indicating if the image data is going to be written by the shader.
sizesize of the object passed as parameter.
Returns:
an int indicating whether the call was succesfull or not.

Use

Note

There must be as many calls to this function as the number of non-independant parameters specified previously with a call to SetCL. See the use of shaders the dedicated sections.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
GetCLShaderState
SetCL
RunCL
GetCLShaderState

Definition at line 331 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetCLParam ( int  shaderId,
int  param,
DTHandle  h,
bool  read = true,
bool  write = true 
)

Definition at line 332 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetCLParam ( int  shaderId,
int  param,
int  samplerParam,
DTTexture handle,
bool  read = true,
bool  write = false 
)

Definition at line 333 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetCLParam ( int  shaderId,
int  param,
DTTexture handle,
bool  read = true,
bool  write = false 
)
inline

Definition at line 520 of file DirectTraceAPI.h.

void DTRayBuffer::SetCLQueue ( int  queue)

This function sets the OpenCL queue used for subsequent shader calls.

)

Parameters:
queuethe queue number
Returns:

Use

Computing Jobs/Shaders in parallel, or using multiple OpenCL devices.

Note

See the number of queues per OpenCL device.

Compatibility

Supported by the OpenCL version of DirectTrace

See also:

Definition at line 339 of file DirectTraceAPI.cpp.

void DTRayBuffer::SetFrustumRaysFromGLProjectionMatrix ( )

Generates frustum ray coordinates from the OpenGL projection matrix.

Returns:

Use

Replacing some OpenGL code

Note

Not implemented in early versions of the library.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Resize
SetRandomlyDisplacedFrustumRaysFromPyramidF
SetRays4D
DTRayBuffer::SetFrustumRaysFromPyramidF

Definition at line 336 of file DirectTraceAPI.cpp.

void DTRayBuffer::SetFrustumRaysFromPyramidF ( float *  center,
float *  corners[4],
SUBCOPY_STYLE  layout = SUBCOPY_NONE,
int  layoutId = 0 
)

Generates frustum ray coordinates from a pyramid described from a 3D center and four corner 3D coordinates.

Parameters:
centerThe common source for the rays.
cornersFour pointers to the four corner coordinates.
layoutThe internal memory arrangement. Not implemented yet.
layoutIdNot used yet.
Returns:

Use

A way to initializing frustum rays. Other methods exist, including using shaders.

Note

Size of the matrix should have been specified first with the Resize() operator. Currently, rays are interleaved in blocks of 8x8 rays. This should be kept in mind when, for instance, performing shader operations that require neighbor's data.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Resize
SetRandomlyDisplacedFrustumRaysFromPyramidF
SetRays4D
SetFrustumRaysFromGLProjectionMatrix

Definition at line 259 of file DirectTraceAPI.cpp.

void DTRayBuffer::SetRandomlyDisplacedFrustumRaysFromPyramidF ( float *  center,
float *  corners[4],
SUBCOPY_STYLE  layout = SUBCOPY_NONE,
int  layoutId = 0 
)

Generates frustum ray coordinates from a pyramid described from a 3D center and four corner 3D coordinates. Locations of rays inside the pixel are uniformly shifted on x and y by a random value not exceeding the size of one pixel.

Parameters:
centerThe common source for the rays.
cornersFour pointers to the four corner coordinates.
layoutThe internal memory arrangement. Not implemented yet.
layoutIdNot used yet.
Returns:

Use

A way to initializing frustum rays. Other methods exist, including using shaders. This is to be used for Anti-Aliasing purposes.

Note

Size of the matrix should have been specified first with the Resize() operator. Currently, rays are interleaved in blocks of 8x8 rays. This should be kept in mind when, for instance, performing shader operations that require neighbor's data.

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Resize
SetFrustumRaysFromPyramidF
SetRays4D
SetFrustumRaysFromGLProjectionMatrix

Definition at line 260 of file DirectTraceAPI.cpp.

void DTRayBuffer::SetRays4D ( int  nbRays,
float *  pos,
float *  dir 
)

Transfers (linearly) nbRays from user arrays to a RayBuffer object.

Parameters:
nbRaysNumber of rays.
posstarting locations for rays. Each point should be a 4D coordinate.
dirdirections for rays. Each direction should be a 4D coordinate.
Returns:

Use

Note

The 4th components may not be meaningful to the programmer. The 4th direction component is used for storing t values in other parts of the DirecTrace pipeline. Arrays may be automatically resized if necessary as (nbRays,1).

Compatibility

Supported by OpenCL versions of DirectTrace.

See also:
Resize
SetFrustumRaysFromPyramidF
SetRays4D
SetFrustumRaysFromGLProjectionMatrix

Definition at line 266 of file DirectTraceAPI.cpp.

int DTRayBuffer::SetSimplifiedCL ( int  shaderId,
char *  openCLShaderCode,
char *  compilationOptions,
int  extraArgs 
)

Definition at line 329 of file DirectTraceAPI.cpp.

void DTRayBuffer::SetZBuffer ( )
void DTRayBuffer::Shuffle ( )

Shuffle the active rays inside a ray buffer.

Returns:

Use

Can be used to randomize the position of photons inside a photon list.

Note

There may be a performance issues with the early instances of this function. May not be recommended for real-time applications.

Compatibility

Supported by OpenCL versions of DirectTrace.

Definition at line 269 of file DirectTraceAPI.cpp.

void DTRayBuffer::Shuffle ( DTHandle argHandleV[])

Definition at line 289 of file DirectTraceAPI.cpp.

void DTRayBuffer::Touch ( COHERENCY_TYPE  rayType = FULLY_INCOHERENT_RAYS)

This function must be called prior to a call to Intersector() when RayBuffer positions and directions have been modified by a call to a shader function.

Parameters:
rayTypeSpecifies the type of spatial coherency after the use of a (RayBuffer) shader.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
Run
RunCL

Definition at line 272 of file DirectTraceAPI.cpp.


The documentation for this class was generated from the following files: