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

class provides tools related to handling scene properties. More...

#include <DirectTraceAPI.h>

+ Inheritance diagram for DTScene:
+ Collaboration diagram for DTScene:

List of all members.

Public Member Functions

 DTScene (DirectTraceAPI &api)
 ~DTScene ()
void AllocateSpaceForNPrimitives (PRIMITIVE primitive, long long nbPrimitives)
 This function internally manages space for data related to primitives of type primitive. The function will destroy previously allocated primitives of a given Primitive type and the primitive attributes. While the use of this function is not required as lists may automatically resize themselves when needed, it will help minimizing the number of operations required for resizing. Also note that the allocation of vertices is not affected by this function. This is specified when creating a new Material.
void Begin (PRIMITIVE primitive, int materialId=0)
 This function prepares for streaming primitives of type primitive. Various functions can be called in the middle of a Begin/End section, including Vertex3fv, PrimitiveAttrib, and etc...
The OpenGL Modelview matrix must be fixed outside of a begin/end section.
void Clone (DTScene &source)
 This function creates a cloned scene of a particular scene, which is useful when making use of explicit multithreading where the same scene can be used by two concurrent processes.
void DeleteAllMaterials ()
 This function deletes all material associated with a scene.
void DeleteMaterial (int id)
 This function deletes a material previously created with NewMaterial.
void End ()
 This function ends a series of calls that started with a call to Begin().
void Intersector (DTRayBuffer &rays, int threads=1)
 This function computes the intersection between the rays passed as parameters and the scene. To be valid, Rays' starting points and directions should be created first using one of the different possibilities given by the interface (Frustum rays, shaders, etc)...
void IntersectorCL (DTRayBuffer &rays, int threads=1)
void MaterialAttrib (int materialId, void *attribs, int charCount)
 This function streams data to a given material described with materialId. The total amount of data sent to the library after multiple calls to MaterialAtttrib should correspond to the one specified when the material has been created.
int NewMaterial (int bytesPerMaterial, int bytesPerPrimitive, int bytesPerVertex, int hintNumberOfPrimitives, int hintNumberOfVertices)
 This function configures scene properties around materials and pre-allocates some memory. The use of this function is almost compulsory as primitives will usually require extra data per vertex or per triangle. This function is closely related to the primitive description given to the library in later calls. Especially, the size of attributes per material, per primitive and per vertex is/must be fixed for a given material. A material can be shared by different types of primitives, with some restrictions. Currently, a material shall not be shared between single and double precision primitives
The maximum number of materials that can be used is specified by MAX_DTMATERIALS.
void PrimitiveAttrib (void *data, int size)
 This function streams data to a primitive attribute list for a given material. The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttrib should be less or equal to the one specified when the related material has been created. A call to Vertex(...) is required to validate the data.
void PrimitiveAttribfv (float *pt, int floatCount)
 This function streams float data to a primitive attribute list for a given material. The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttrib should be less or equal to the one specified when the related material has been created. A call to Vertex(...) is required to validate the data.
void PrimitiveAttribMV3fv (float *pt)
 This function streams 3 floats to a primitive attribute list for a given material. The 3 floats are multiplied by the current modelview matrix (4th coordinate being 1). The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttribMV3fv should correspond to the one specified when the related material has been created. A call to Vertex() is required to validate the data.
void PrimitiveAttribMV4fv (float *pt)
 This function streams 4 floats to a primitive attribute list for a given material. The 4 floats are multiplied by the current modelview matrix. The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttribMV4fv should correspond to the one specified when the related material has been created. A call to Vertex() is required to validate the data.
void PrimitiveAttribdv (double *pt, int floatCount)
void PrimitiveAttribMV3dv (double *pt)
void PrimitiveAttribMV4dv (double *pt)
void Reset ()
void Vertices (int *indices)
 This function setup an indexed primitive from n indices passed as a vector. Only works for primitive types that support vertex indexing. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). n is depending on the primitive type, e.g., 3 for DT_TRIANGLES. The indices shall be retrieved first from calls to the Vertex() function when creating a vertex attribute list.
void Vertex3fv (float *xyz)
 This function streams 3 floating point vertex coordinates to setup the current primitive. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.
void VertexMV3fv (float *xyz)
 This function streams 3 floating point vertex coordinates to setup the current primitive, with vertex coodinates being multiplied by the modelview matrix. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.
void Vertex4fv (float *xyzw)
 This function streams 4 floating point vertex coordinates to setup the current primitive. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.
void VertexMV4fv (float *xyzw)
 This function streams 4 floating point vertex coordinates to setup the current primitive, with vertex coodinates being multiplied by the modelview matrix. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.
void Vertex3dv (double *xyz)
void VertexMV3dv (double *xyz)
void Vertex4dv (double *xyzw)
void VertexMV4dv (double *xyzw)
void VertexAttrib (void *pt, int charCount)
void VertexAttribfv (float *pt, int floatCount)
void VertexAttribMV3fv (float *pt)
void VertexAttribMV4fv (float *pt)
void RemoveAllUnreferencedVertices (int materialId)
 This function removes all unreference vertices for a given material. To be usable, vertex indexed primitives must be used. on in conjunction with vertex indexed primitives.
void Delete ()
 This function deletes all data related to a scene.
long long Vertex ()
void ModifyMaterialAttrib (int id)
void MaterialId (int id)
void UVCoordsAtIntersection (DT_RAYS_HANDLE rays, DT_IMAGE_HANDLE uvCoords)
void Hint (SCENE_HINTS hint)
- 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

class provides tools related to handling scene properties.

Definition at line 618 of file DirectTraceAPI.h.


Constructor & Destructor Documentation

DTScene::DTScene ( DirectTraceAPI api)

Definition at line 211 of file DirectTraceAPI.cpp.

DTScene::~DTScene ( )

Definition at line 212 of file DirectTraceAPI.cpp.


Member Function Documentation

void DTScene::AllocateSpaceForNPrimitives ( PRIMITIVE  primitive,
long long  nbPrimitives 
)

This function internally manages space for data related to primitives of type primitive. The function will destroy previously allocated primitives of a given Primitive type and the primitive attributes. While the use of this function is not required as lists may automatically resize themselves when needed, it will help minimizing the number of operations required for resizing. Also note that the allocation of vertices is not affected by this function. This is specified when creating a new Material.

Parameters:
primitivethe type of the primitive for allocation
nbPrimitivesHow many primitives of the described type may be sent to the API.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
NewMaterial

Definition at line 246 of file DirectTraceAPI.cpp.

void DTScene::Begin ( PRIMITIVE  primitive,
int  materialId = 0 
)

This function prepares for streaming primitives of type primitive. Various functions can be called in the middle of a Begin/End section, including Vertex3fv, PrimitiveAttrib, and etc...
The OpenGL Modelview matrix must be fixed outside of a begin/end section.

Parameters:
primitiveThe type of primitive that is used.
materialIdThe material to be used for the primitives to follow. Must be a valid Id.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Example

DTScene scene(dtAPI);
float vertex[6][3]={...};
...
scene.Begin(DT_TRIANGLES,0);
//first triangle
scene.Vertex3fv(vertex[0]);
scene.Vertex3fv(vertex[1]);
scene.Vertex3fv(vertex[2]);
//second triangle
scene.Vertex3fv(vertex[3]);
scene.Vertex3fv(vertex[4]);
scene.Vertex3fv(vertex[5]);
scene.End();
Output:
See also:
End
NewMaterial
Vertex3fv

Definition at line 227 of file DirectTraceAPI.cpp.

void DTScene::Clone ( DTScene source)

This function creates a cloned scene of a particular scene, which is useful when making use of explicit multithreading where the same scene can be used by two concurrent processes.

Parameters:
sourceThe original scene to be cloned. Should be a cloned scene.
Returns:
void

Use

Explicit parallelism.

Note

The function mainly duplicates all variables that cannot be accessed concurently, but avoiding full copies of the original
You should use this function keeping a few principles in mind:
Behavior is undefined if the original scene is a clone. You should also make sure in your application that the original scene is deleted after its clones. Finally, the function is currently only useful when using the clones with the Intersector function. Clones are not useful yet for parallelizing other features of the API like scene creation related functions (Begin, Vertex3f, etc...)

Compatibility

Supported by versions of DirectTrace that support explicit multithreading.

See also:
Intersector

Definition at line 213 of file DirectTraceAPI.cpp.

void DTScene::Delete ( )

This function deletes all data related to a scene.

Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Definition at line 231 of file DirectTraceAPI.cpp.

void DTScene::DeleteAllMaterials ( )

This function deletes all material associated with a scene.

Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Example

See also:
NewMaterial
DeleteMaterial
DeleteAllMaterials
MaterialAttrib

Definition at line 215 of file DirectTraceAPI.cpp.

void DTScene::DeleteMaterial ( int  id)

This function deletes a material previously created with NewMaterial.

Parameters:
idThe id of the material to be deleted. Must have been created first.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Example

//Getting an id for a new material.
int materialId=scene.NewMaterial(0,bytesPerPrimitive, bytesPerVertex,0,0);//Required before a Begin/End section is called, unless a pre-defined material id is used (e.g., 0).
...
//Removing/deleting the material when not needed anymore.
scene.DeleteMaterial(materialId);
Output:
See also:
NewMaterial
DeleteMaterial
DeleteAllMaterial
MaterialAttrib

Definition at line 244 of file DirectTraceAPI.cpp.

void DTScene::End ( )

This function ends a series of calls that started with a call to Begin().

Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Example

See also:
End
Begin

Definition at line 228 of file DirectTraceAPI.cpp.

void DTScene::Hint ( SCENE_HINTS  hint)

Definition at line 250 of file DirectTraceAPI.cpp.

void DTScene::Intersector ( DTRayBuffer rays,
int  threads = 1 
)

This function computes the intersection between the rays passed as parameters and the scene. To be valid, Rays' starting points and directions should be created first using one of the different possibilities given by the interface (Frustum rays, shaders, etc)...

Parameters:
raysRays to be intersected with the scene.
threadsNumber of threads used to accelerate the intersector. Value is 1 if not declared.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
SetFrustumRaysFromPyramidF
FrustumRaysFromProjectionMatrix

Definition at line 229 of file DirectTraceAPI.cpp.

void DTScene::IntersectorCL ( DTRayBuffer rays,
int  threads = 1 
)

Definition at line 230 of file DirectTraceAPI.cpp.

void DTScene::MaterialAttrib ( int  materialId,
void *  pt,
int  charCount 
)

This function streams data to a given material described with materialId. The total amount of data sent to the library after multiple calls to MaterialAtttrib should correspond to the one specified when the material has been created.

This function streams data to a given material described with materialId. The amount of data sent to the library should correspond to the one specified when the material has been created.

Parameters:
materialIdId of the material concerned
ptpointer to the data structure to be passed.
charCountAmount of bytes to be copied.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
NewMaterial
Parameters:
materialIdId of the material concerned
ptpointer to the data structure to be passed.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
NewMaterial

Definition at line 247 of file DirectTraceAPI.cpp.

void DTScene::MaterialId ( int  id)

Definition at line 217 of file DirectTraceAPI.cpp.

void DTScene::ModifyMaterialAttrib ( int  id)

Definition at line 216 of file DirectTraceAPI.cpp.

int DTScene::NewMaterial ( int  bytesPerMaterial,
int  bytesPerPrimitive,
int  bytesPerVertex,
int  hintNumberOfPrimitives = 1,
int  hintNumberOfVertices = 3 
)

This function configures scene properties around materials and pre-allocates some memory. The use of this function is almost compulsory as primitives will usually require extra data per vertex or per triangle. This function is closely related to the primitive description given to the library in later calls. Especially, the size of attributes per material, per primitive and per vertex is/must be fixed for a given material. A material can be shared by different types of primitives, with some restrictions. Currently, a material shall not be shared between single and double precision primitives
The maximum number of materials that can be used is specified by MAX_DTMATERIALS.

Parameters:
bytesPerPrimitiveSize of the data attached to the material. Size must be coherent with the subsequent calls made to MaterialAttrib.
bytesPerPrimitiveSize of a primitive attribute that must be reserved for each primitive passed to the scene. This must be coherent with the subsequent calls made to PrimitiveAttrib, PrimitiveAttribMV3fv, PrimitiveAttribMV4fv.
bytesPerVertexSize of a vertex attribute that must be reserved for each primitive passed to the scene. This must be coherent with the subsequent calls made to PrimitiveAttrib, PrimitiveAttribMV3fv, PrimitiveAttribMV4fv.
hintNumberOfPrimitivesThis argument helps allocating lists by giving a hint on the number of primitives that will be used with the new material. It should be specified if the number is known as it will optimize memory usage and performance.
hintNumberOfVerticesThis argument helps allocating lists by giving a hint on the number of vertices that will be used with the new material. It should be specified if the number is known as it will optimize memory usage and performance.
Returns:
The id of the material created for later usage.

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Example

DTScene scene(dtAPI);
MyMaterial material;
float color[3]={...};
int bytesPerMaterial=sizeof(MyMaterial);
int bytesPerPrimitive=3*sizeof(float);//3 colors associated with each primitive for flat shading.
int bytesPerVertex=0; //Currently not implemented. Should be 0
int materialId=scene.NewMaterial(0,bytesPerPrimitive, bytesPerVertex,0,0);//Required before a Begin/End section is called, unless a pre-defined material id is used (e.g., 0).
Output:
See also:
NewMaterial
DeleteMaterial
DeleteMaterialList
MaterialAttrib
PrimitiveAttrib

Definition at line 248 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttrib ( void *  pt,
int  charCount 
)

This function streams data to a primitive attribute list for a given material. The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttrib should be less or equal to the one specified when the related material has been created. A call to Vertex(...) is required to validate the data.

Parameters:
ptpointer to the data structure to be passed.
charCountAmount of bytes to be copied.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
PrimitiveAttrib
PrimitiveAttribfv
PrimitiveAttribMV3fv
PrimitiveAttribMV4fv
PrimitiveAttribdv
PrimitiveAttribMV3dv
PrimitiveAttribMV4dv

Definition at line 237 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttribdv ( double *  pt,
int  floatCount 
)

Definition at line 241 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttribfv ( float *  pt,
int  floatCount 
)

This function streams float data to a primitive attribute list for a given material. The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttrib should be less or equal to the one specified when the related material has been created. A call to Vertex(...) is required to validate the data.

Parameters:
ptfloating point pointer to the data structure to be passed.
floatCountnumber of floats to be copied.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
PrimitiveAttrib
PrimitiveAttribfv
PrimitiveAttribMV3fv
PrimitiveAttribMV4fv
PrimitiveAttribdv
PrimitiveAttribMV3dv
PrimitiveAttribMV4dv

Definition at line 238 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttribMV3dv ( double *  pt)

Definition at line 242 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttribMV3fv ( float *  pt)

This function streams 3 floats to a primitive attribute list for a given material. The 3 floats are multiplied by the current modelview matrix (4th coordinate being 1). The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttribMV3fv should correspond to the one specified when the related material has been created. A call to Vertex() is required to validate the data.

Parameters:
ptpointer to an array of 3 floating point values.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
PrimitiveAttrib
PrimitiveAttribfv
PrimitiveAttribMV3fv
PrimitiveAttribMV4fv
PrimitiveAttribdv
PrimitiveAttribMV3dv
PrimitiveAttribMV4dv

Definition at line 239 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttribMV4dv ( double *  pt)

Definition at line 243 of file DirectTraceAPI.cpp.

void DTScene::PrimitiveAttribMV4fv ( float *  pt)

This function streams 4 floats to a primitive attribute list for a given material. The 4 floats are multiplied by the current modelview matrix. The function should be called inside a Begin()/End() section. The total amount of data sent to the library after multiple calls to PrimitiveAttribMV4fv should correspond to the one specified when the related material has been created. A call to Vertex() is required to validate the data.

Parameters:
ptpointer to an array of 4 floating point values.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
PrimitiveAttrib
PrimitiveAttribfv
PrimitiveAttribMV3fv
PrimitiveAttribMV4fv
PrimitiveAttribdv
PrimitiveAttribMV3dv
PrimitiveAttribMV4dv

Definition at line 240 of file DirectTraceAPI.cpp.

void DTScene::RemoveAllUnreferencedVertices ( int  materialId)

This function removes all unreference vertices for a given material. To be usable, vertex indexed primitives must be used. on in conjunction with vertex indexed primitives.

Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

Definition at line 245 of file DirectTraceAPI.cpp.

void DTScene::Reset ( )

Definition at line 214 of file DirectTraceAPI.cpp.

void DTScene::UVCoordsAtIntersection ( DT_RAYS_HANDLE  rays,
DT_IMAGE_HANDLE  uvCoords 
)

Definition at line 249 of file DirectTraceAPI.cpp.

long long DTScene::Vertex ( )

Definition at line 232 of file DirectTraceAPI.cpp.

void DTScene::Vertex3dv ( double *  xyz)

Definition at line 223 of file DirectTraceAPI.cpp.

void DTScene::Vertex3fv ( float *  pt)

This function streams 3 floating point vertex coordinates to setup the current primitive. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.

Parameters:
ptpointer to a vector of 3 float values.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
Vertex3fv
Vertex4fv
VertexMV3fv
VertexMV4fv
Vertices

Definition at line 219 of file DirectTraceAPI.cpp.

void DTScene::Vertex4dv ( double *  xyzw)

Definition at line 225 of file DirectTraceAPI.cpp.

void DTScene::Vertex4fv ( float *  pt)

This function streams 4 floating point vertex coordinates to setup the current primitive. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.

Parameters:
ptpointer to a vector of 4 float values.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
Vertex3fv
Vertex4fv
VertexMV3fv
VertexMV4fv
Vertices

Definition at line 221 of file DirectTraceAPI.cpp.

void DTScene::VertexAttrib ( void *  pt,
int  charCount 
)

Definition at line 218 of file DirectTraceAPI.cpp.

void DTScene::VertexAttribfv ( float *  pt,
int  floatCount 
)

Definition at line 234 of file DirectTraceAPI.cpp.

void DTScene::VertexAttribMV3fv ( float *  pt)

Definition at line 235 of file DirectTraceAPI.cpp.

void DTScene::VertexAttribMV4fv ( float *  pt)

Definition at line 236 of file DirectTraceAPI.cpp.

void DTScene::VertexMV3dv ( double *  xyz)

Definition at line 224 of file DirectTraceAPI.cpp.

void DTScene::VertexMV3fv ( float *  pt)

This function streams 3 floating point vertex coordinates to setup the current primitive, with vertex coodinates being multiplied by the modelview matrix. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.

Parameters:
ptpointer to a vector of 3 float values.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
Vertex3fv
Vertex4fv
VertexMV3fv
VertexMV4fv
Vertices

Definition at line 220 of file DirectTraceAPI.cpp.

void DTScene::VertexMV4dv ( double *  xyzw)

Definition at line 226 of file DirectTraceAPI.cpp.

void DTScene::VertexMV4fv ( float *  pt)

This function streams 4 floating point vertex coordinates to setup the current primitive, with vertex coodinates being multiplied by the modelview matrix. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). When the last primitive vertex is entered, a full primitive is then processed.

Parameters:
ptpointer to a vector of 4 float values.
Returns:
void

Use

Note

Compatibility

Supported by all versions of DirectTrace.

See also:
Vertex3fv
Vertex4fv
VertexMV3fv
VertexMV4fv
Vertices

Definition at line 222 of file DirectTraceAPI.cpp.

void DTScene::Vertices ( int *  indices)

This function setup an indexed primitive from n indices passed as a vector. Only works for primitive types that support vertex indexing. The function must be called inside a Begin(primitive)/End() section (with DT_VERTEX as primitive not allowed). n is depending on the primitive type, e.g., 3 for DT_TRIANGLES. The indices shall be retrieved first from calls to the Vertex() function when creating a vertex attribute list.

Parameters:
indicesvector of integers
Returns:
void

Use

Note

Compatibility

Not supported yet.

See also:
Vertex3fv
Vertex4fv
VertexMV3fv
VertexMV4fv
Vertices
Vertex

Definition at line 233 of file DirectTraceAPI.cpp.


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