Rayforce: LibRT

void* rtCreateContext	(	char *	engine,
		char *	requirements,
		char *	parameters
	)

Create a context.

Parameters:

	engine	String specifying the desired engine as identified by RT_ENGINE.
	requirements	Space-separated list of extensions and specifications required to be supported.
	parameters	Parameters to be passed to the implementation.

rtCreateContext() creates a new context and returns its handle. If rtCreateContext() fails to create the context, a zero pointer is returned. The parameters engine, requirements and params, if non-zero, have to be zero terminated strings. Zero pointers are treated as empty strings.

The format of engine is expected to be identical or similar to the result of a call to rtGetString() with RT_ENGINE as parameter on a valid context. It is treated as a hint for fuzzy matching and may be ignored.

The requirements parameter is to be a list of items separated by space characters, and the created context created is garanteed to support all the capabilities or extensions requested. Consult extension specifications for the exact description of capabilities. rtCreateContext() will fail if no implementation can be found that supports all extensions and capabilities requested.

The parameter parameters is passed to the underlying implementation and its format is implementation dependant. It is treated as a hint and may not cause rtCreateContext() to fail.

All commands operate on the bound context ; scene, group, model, object, source and buffer entities are all specific to a context and can not be shared between multiple contexts. If resources are to be shared, use of multiple scenes within a same context is recommended.

void rtBindContext ( void * context )

Bind a context.

Parameters:

context

Specifies the context to be bound.

rtBindContext() makes context current. Behavior is undefined if context is not a valid context.

All operations affect the bound context; object names, source names and buffer names are all specific to one context and can't be shared between multiple contexts.

void rtDestroyContext ( void * context )

Destroy a context.

Parameters:

context

Specifies the context to be destroyed.

rtDestryContext() destroys the specified context immediately, freeing all allocated resources. Behavior is undefined if context is not a valid context.

All commands operate on the bound context ; scene, group, model, object, source and buffer entities are all specific to a context and can not be shared between multiple contexts. If resources are to be shared, use of multiple scenes is advised.

rtint rtGetError ( )

Query error information.

Returns:: Bit mask of error bit flags

rtGetError() returns the value of the error flag. Each detectable error is assigned a numeric code and symbolic name. When an error occurs, a bit of the error flag corresponding to the error code value is set so that multiple different errors can then be recorded before the next call to rtGetError(). The error flag is reset to RT_NO_ERROR when rtGetError() is called.

Each context is entirely independant from the others, each context also has its own error flag. The value of the error flag is undefined if there is no valid context bound.

Each error constant represents a bit of the error flag that can be tested to verify if the error occured. The errors are defined as follow :

RT_NO_ERROR: No error has been recorded. The value of this symbolic constant is guaranteed to be zero.
RT_INVALID_NAME: An invalid name has been passed to a command. The operation is skipped for the invalid name but, as specified, the command may still operate on other valid names provided.
RT_INVALID_BINDING: A command could not be executed because the current binding is invalid. The invalid binding can be a context, an object, a source or a buffer.
RT_INVALID_PARAMETER: The operation could not be performed because at least one of the parameters passed to the function was not valid.
RT_INVALID_OPERATION: The specified operation is not allowed in the current state. The faulty command is ignored unless, as specified, the command is to repeat an operation on multiple entities and only fails for one or more entities.
RT_OUT_OF_MEMORY: There is not enough memory left to execute the command. The state of the implementation is undefined, it is acceptable for the program to terminate immediately when this error occurs.

char* rtGetString ( rtint target )

Query various information global to the context.

Parameters:

target

Specifies a symbolic constant, RT_PROVIDER, RT_ENGINE, RT_VERSION, RT_EXTENSIONS, RT_SPECIFICATIONS, RT_BUILD and RT_CONTACT are accepted.

Returns:: Returns a string describing the information queried.

rtGetString() returns a pointer to a static string describing the current implementation.

The parameter name can be one of the following:

RT_PROVIDER: Returns the person, group or company responsible for the implementation. This name does not change from release to release.
RT_ENGINE: Returns the name of the engine. This name is typically specific to a particular implementation or hardware platform. It does not change from release to release.
RT_VERSION: Returns a version or release number to describe supported features, the format is always major_number.minor.number while implementation-specific information may follow, seperated by a space character.
RT_EXTENSIONS: Returns a space-separated list of supported extensions.
RT_SPECIFICATIONS: Returns a space-separated list of internal values describing the implementation. Similarily to extensions, the values can be used by the rtCreateContext() command to request support for certain capabilities.
RT_BUILD: Returns an implementation-specific string describing the version or build number of the implementation.
RT_CONTACT: Returns an implementation-specific string describing how to contact the provider.

All strings are zero terminated. If an error is generated, rtGetString() returns zero.

void* rtGetProcAddress ( char * procname )

Query address of a procedure for the context.

Parameters:

procname

Specifies the name of a command.

Returns:: Returns the address of the command specified.

rtGetProcAddress() returns a pointer to the command identified by procname.

rtGetProcAddress() is meant to be used to query the address of additional procedures exposed by extensions that may not be available on all implementations. If procname is unknown or unavailable for the current context, a zero pointer is returned.

void rtWait ( rtint status )

Wait for context status.

Parameters:

status

Specifies a symbolic constant indicating the desired behavior. RT_WAIT_HINT_NONBLOCK, RT_WAIT_HINT_ANY, RT_WAIT_HINT_ALL and RT_WAIT_HINT_READY are accepted.

rtWait() may block the execution of the calling thread, waiting for the implementation to reach the desired status, and executes all pending buffer callbacks for completed ray-tracing operations. rtWait() is a context command and applies to all scenes of the current context.

Callbacks are garanteed to be executed by the same thread that called rtWait() and stack alignment is preserved for the largest data type available to the architecture.

The parameter status describes what status is to be reached before the function returns. The accepted constants are :

RT_WAIT_HINT_NONBLOCK: Instructs the implementation to return immediately after pending callbacks are executed, the thread is not blocked in any circumstance.
RT_WAIT_HINT_ANY: Instructs the implementation to block until any ray-tracing work is completed, garanteeing at least one callback if any ray-tracing command is awaiting completion.
RT_WAIT_HINT_READY: This option can ensure a constant flow of ray-tracing operations without risking to choke the implementation. The command blocks until the implementation acknowledges it is ready to accept more work. Pending callbacks are then executed before the command returns.
RT_WAIT_HINT_ALL: Instructs the implementation to block until all ray-tracing commands have been completed before executing callbacks.

void rtContextEnv	(	rtint	target,
		rtint	value,
		void *	data
	)

Set or query context environment parameters.

Parameters:

	target	Specifies an environment parameter.
	value	Specifies the value or mode to be assigned to the parameter.
	data	Specifies data to be assigned to the parameter.

rtContextEnv defines environment parameters global to the currently bound context. If the RT_EXT_THREAD_CONTROL extension is supported, RT_THREAD_COUNT_HINT is an accepted constant for the target parameter.

If target is RT_THREAD_COUNT_HINT, the command provides a hint to the implementation on the number of local concurrent threads for execution of the supplied commands. The count of threads is provided by the value parameter and may be clamped or ignored.

void rtGenScenes	(	rtint	count,
		rtint *	names
	)

Generate scene names.

Parameters:

	count	Specifies the number of scenes to be generated.
	names	Specifies an array in which the generated scene names are stored.

rtGenScenes() returns count scene names in names. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to rtGenScenes().

Scene names returned by a call to rtGenScenes() are not returned by subsequent calls, unless they are first deleted with rtDeleteScenes(). The generated scenes are empty.

Scene entities are global to the current context. Object and source entities are specific to the currently bound scene when they are generated. Upon deletion of a scene, all objects and sources it contains are deleted.

void rtBindScene ( rtint name )

Bind a scene name.

Parameters:

name

Specifies the name of the scene to be bound.

rtBindScene() makes the scene identified by name current. Attempting to bind an invalid scene name sets the error flag to RT_INVALID_NAME but does not break the previous binding.

Scene entities are global to the current context. Object and source entities are specific to the currently bound scene when they are generated. Upon deletion of a scene, all objects and sources it contains are deleted.

void rtDeleteScenes	(	rtint	count,
		rtint *	names
	)

Delete scene names.

Parameters:

	count	Specifies the number of scenes to be deleted.
	names	Specifies an array of scene names to be deleted.

rtDeleteScenes() deletes count scenes named by the elements of the array names. After a scene is deleted, its name is free for reuse by rtGenScenes(). If a scene that is currently bound is deleted, the scene binding becomes invalid.

rtDeleteScenes() skips names that do not correspond to existing scenes, setting the error flag to RT_INVALID_NAME.

Scene entities are global to the current context. Object and source entities are specific to the currently bound scene when they are generated. Upon deletion of a scene, all objects and sources it contains are deleted.

void rtTraceRays	(	rtint	count,
		void *	value,
		void *	callback,
		void *	asynccallback
	)

Trace rays.

Parameters:

	count	Specifies the count of rays to be traced.
	value	Specifies a value to be passed to the callback function.
	callback	Specifies the address of a callback function.
	asynccallback	Specifies the address of an asynchroneous callback function.

rtTraceRays() is a non-blocking operation that emits count rays. The currently bound buffer entity defines the parameters of the rtTraceRays() command. This includes what attributes are provided for each ray, where the information is to be read from and how the results should be provided. The specified callback function is executed at the next rtWait() command following completion of the ray-tracing operation. The specified asynccallback function is executed asynchroneously, immediately after completion of the task. Both pointers can be defined as zero if no function is to be called. All memory locations assigned to the currently bound buffer must remain valid until execution of callback.

The callback and asynchroneous callback functions are to be defined as :

void callback(void *value, rtint status);

The parameter value is the same value that was specified as parameter to the rtTraceRays() command. The status parameter is defined to be zero on success. During ray-tracing operations, the currently bound buffer is locked until callback is executed and no command is allowed on this buffer except rtDeleteBuffers(). If the buffer, scene or context attached to the queued ray-tracing command is deleted prior to completion of the task, the specified callback shall be executed prior to the return of the entity deletion function. The parameter status of the callback function may be zero if the task was completed or RT_CANCELED_OPERATION to indicate failure. Other non-zero values for the status parameter may indicate an incorrect buffer state.

Several attributes may be provided for each ray as follows : ray vectors, source names to use as the origin of each ray, displacement from the origin of each ray, source names to be updated to match the ray intersection points, and additional flags for each ray.

Vectors are mandatory to be provided by the currently bound buffer as set by rtSupplyVectors(). All vectors are required to be non-zero in length or behavior is undefined.

By default, the origin of all rays is set to the origin of the currently bound source. Alternatively, the command rtSupplySources() can be used to assign to the current buffer an array of source names to define the origin of rays.

Displacements from the origin of rays can be provided through the command rtSupplyDisplacements().

Rays can update the origin of sources to the points of intersection with the scene geometry. The command rtSupplyEndSources() is used to set the location where the currently bound buffer is to read the source names.

Additional flags may be provided for each ray by the command rtSupplyFlags().

Two mechanisms are provided to receive the results from the ray-tracing operation ; data collection and ray callbacks. See rtBufferEnv() for more information.

void rtBuild ( )

Build or update scene.

rtBuild() updates the currently bound scene. It is a required operation prior to tracing rays whenever changes have been made to any object, models or groups present in the scene.

Upon the execution of rtBuild(), the origin of all sources within the scene are invalidated. Behavior is undefined if sources are used before being given assigned a new origin.

void rtGenGroups	(	rtint	count,
		rtint *	names
	)

Generate group names.

Parameters:

	count	Specifies the number of groups to be generated.
	names	Specifies an array in which the generated group names are stored.

rtGenGroups() returns count group names in names. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to rtGenGroups().

Group names returned by a call to rtGenGroups() are not returned by subsequent calls, unless they are first deleted with rtDeleteGroups(). The generated groups are empty.

Group entities are global to the current context.

void rtBindGroup ( rtint name )

Bind a group name.

Parameters:

name

Specifies the name of the group to be bound.

rtBindGroup() makes the group identified by name current. Attempting to bind an invalid group name sets the error flag to RT_INVALID_NAME but does not break the previous binding.

A pair of rtBegin() and rtEnd() commands can be used to define the geometry of the currently bound group. It replaces any geometry the group contains.

Group entities are global to the current context.

void rtDeleteGroups	(	rtint	count,
		rtint *	names
	)

Delete group names.

Parameters:

	count	Specifies the number of groups to be deleted.
	names	Specifies an array of group names to be deleted.

rtDeleteGroups() deletes count groups named by the elements of the array names. After a group is deleted, its name is free for reuse by rtGenGroups(). If a group that is currently bound is deleted, the group binding becomes invalid.

rtDeleteGroups() skips names that do not correspond to existing groups, setting the error flag to RT_INVALID_NAME.

If a group is present in the definition of any model, rtDeleteGroups() will skip it, setting the error flag to RT_INVALID_OPERATION.

Group entities are global to the current context.

void rtBegin ( )

Begin specifying the geometry of a group.

rtBegin() and rtEnd() delimit the geometry that define a group. If the group contains any geometry at the moment rtBegin() is executed, it is cleared.

rtBegin() locks the current context used until the next rtEnd() command, between which only commands to define the current group can be used. The rtAddTrianglef() and rtAddTriangled() commands add a triangle to the definition of a group. Implementations may expose additional primitives through extensions.

If the group is present in the definition of any model, rtBegin() will fail, setting the error flag to RT_INVALID_OPERATION.

Operations outside the scope of the current context are always valid, specifically rtCreateContext(), rtBindContext() and rtDestroyContext(). If any other command is executed between rtBegin() and rtEnd(), the error flag is set and the command is ignored.

Additional note : Support for modifications of the content of groups without clearing them is planned.

void rtEnd ( )

End specifying the geometry of a group.

rtBegin() and rtEnd() delimit the geometry that define a group. If the group contains any geometry at the moment rtBegin() is executed, it is cleared.

See rtBegin for more information.

void rtAddTrianglef	(	float *	v0,
		float *	v1,
		float *	v2,
		void *	value
	)

Add a triangle with single precision.

Parameters:

	v0	Specifies a pointer to an array of 3 elements, the x, y and z coordinates of the first vertex.
	v1	Specifies a pointer to an array of 3 elements, the x, y and z coordinates of the second vertex.
	v2	Specifies a pointer to an array of 3 elements, the x, y and z coordinates of the third vertex.
	value	Specifies a value to be assigned to the triangle.

The rtAddTrianglef() command is used within a rtBegin() and rtEnd() pair to define the geometry of the currently bound group.

The parameter value is assigned to the triangle primitive. During ray-tracing operations, value can be provided to identify the primitive hit by rays, see rtCollectHitValues(), rtBufferEnv() and rtRayCallback().

void rtAddTriangled	(	double *	v0,
		double *	v1,
		double *	v2,
		void *	value
	)

Add a triangle with double precision.

Parameters:

	v0	Specifies a pointer to an array of 3 elements, the x, y and z coordinates of the first vertex.
	v1	Specifies a pointer to an array of 3 elements, the x, y and z coordinates of the second vertex.
	v2	Specifies a pointer to an array of 3 elements, the x, y and z coordinates of the third vertex.
	value	Specifies a value to be assigned to the triangle.

The rtAddTriangled() command is used within a rtBegin() and rtEnd() pair to define the geometry of the currently bound group.

The parameter value is assigned to the triangle primitive. During ray-tracing operations, value can be provided to identify the primitive hit by rays, see rtCollectHitValues(), rtBufferEnv() and rtRayCallback().

void rtGenModels	(	rtint	count,
		rtint *	names
	)

Generate model names.

Parameters:

	count	Specifies the number of models to be generated.
	names	Specifies an array in which the generated model names are stored.

rtGenModels() returns count model names in names. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to rtGenModels().

Model names returned by a call to rtGenModels() are not returned by subsequent calls, unless they are first deleted with rtDeleteModels(). The generated models are empty.

Model entities are global to the current context.

void rtBindModel ( rtint name )

Bind model name.

Parameters:

name

Specifies the name of the model to be bound.

rtBindModel() makes the model identified by name current. Attempting to bind an invalid model name sets the error flag to RT_INVALID_NAME but does not break the previous binding.

Models hold a list of groups, the representation of a model being the sum of the geometry of the groups it contains. The commands rtAddGroups(), rtRemoveGroups() and rtClearModel() are used to manage the content of models.

Model entities are global to the current context.

void rtDeleteModels	(	rtint	count,
		rtint *	names
	)

Delete model names.

Parameters:

	count	Specifies the number of models to be deleted.
	names	Specifies an array of model names to be deleted.

rtDeleteModels() deletes count models named by the elements of the array names. After a model is deleted, its name is free for reuse by rtGenModels(). If a model that is currently bound is deleted, the model binding becomes invalid.

rtDeleteModels() skips names that do not correspond to existing models, setting the error flag to RT_INVALID_NAME.

If a model is attached to any object, rtDeleteModels() will skip it, setting the error flag to RT_INVALID_OPERATION.

Model entities are global to the current context.

void rtModelEnv	(	rtint	target,
		rtint	value,
		void *	data
	)

Set or query model environment parameters.

Parameters:

	target	Specifies an environment parameter.
	value	Specifies the value, mode or additional information assigned to the parameter.
	data	Specifies data related to the parameter.

rtModelEnv() defines or queries environment parameters assigned to the currently bound model. The accepted constants for the target parameter are RT_BUILD_QUALITY_HINT, RT_BUILD_SPEED_HINT, RT_BUILD_MEMORY_HINT and RT_GET_BUILD_SUMMARY.

If target is RT_BUILD_QUALITY_HINT, RT_BUILD_SPEED_HINT or RT_BUILD_MEMORY_HINT, the command provides a hint for the preparation of the model. The value parameter can either be RT_FLOAT, RT_DOUBLE or RT_LOAD_DEFAULT. The first two constants instruct the implementation to read either one float or one double value from the data pointer. The RT_LOAD_DEFAULT resets the hint to the default implementation value. Before model building, the three hints are normalized so that their sum equals one.

A target of RT_GET_BUILD_SUMMARY retrieves various information on the model's internal representation. The data is written at the address specified in data up to a count of characters specified by value. While typically text, the format and information provided is implementation dependant.

void rtAddGroups	(	rtint	count,
		rtint *	names
	)

Add a list of groups to model.

Parameters:

	count	Specifies the number of groups to be added.
	names	Specifies an array in which the group names are read.

rtAddGroups() adds a list of groups to the currently bound model. No object must presently be attached to the model or the command fails and the error flag is set to RT_INVALID_OPERATION.

rtAddGroups() skips names that do not correspond to existing groups, setting the error flag to RT_INVALID_NAME. rtAddGroups(), rtRemoveGroups() and rtClearModel() typically are inexpensive operations. Attaching a first object to the model notifies the implementation that the definition of the model is complete, at which point the model may be prepared for ray-tracing operations. See rtAttachModel().

Groups can not be redefined or deleted when in use by any model.

void rtRemoveGroups	(	rtint	count,
		rtint *	names
	)

Remove a list of groups from model.

Parameters:

	count	Specifies the number of groups to be removed.
	names	Specifies an array in which the group names are read.

rtRemoveGroups() removes a list of groups to the currently bound model. No object must presently be attached to the model or the command fails and the error flag is set to RT_INVALID_OPERATION.

rtRemoveGroups() skips names that do not correspond to groups present in the model, setting the error flag to RT_INVALID_NAME. rtAddGroups(), rtRemoveGroups() and rtClearModel() typically are inexpensive operations. Attaching a first object to the model notifies the implementation that the definition of the model is complete, at which point the model may be prepared for ray-tracing operations. See rtAttachModel().

Groups can not be redefined or deleted when in use by any model.

void rtClearModel ( )

Clear the list of groups of model.

rtClearModel() removes all groups from the definition of the currently bound model. No object must presently be attached to the model or the command fails and the error flag is set to RT_INVALID_OPERATION.

rtAddGroups(), rtRemoveGroups() and rtClearModel() typically are inexpensive operations. Attaching a first object to the model notifies the implementation that the definition of the model is complete, at which point the model may be prepared for ray-tracing operations. See rtAttachModel().

If the model is attached to any object, rtAddGroups() will fail, setting the error flag to RT_INVALID_OPERATION.

Groups can not be redefined or deleted when in use by any model.

void rtGenObjects	(	rtint	count,
		rtint *	names
	)

Generate object names.

Parameters:

	count	Specifies the number of objects to be generated.
	names	Specifies an array in which the generated object names are stored.

rtGenObjects() returns count object names in names. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to rtGenObjects().

Object names returned by a call to rtGenObjects() are not returned by subsequent calls, unless they are first deleted with rtDeleteObjects(). The generated objects are not attached to a model, contain an identity matrix, have a value of zero, have no parent and the culling mode is set to RT_NONE.

Object entities belong to the currently bound scene when generated. Upon deletion of a scene, all objects it contains are deleted.

void rtBindObject ( rtint name )

Bind an object name.

Parameters:

name

Specifies the name of the object to be bound.

rtBindObject() makes the object identified by name current. Attempting to bind an invalid object name sets the error flag to RT_INVALID_NAME but does not break the previous binding.

Objects are instances of models within a particular scene. They hold a matrix to define the position and orientation of the model's geometry within the scene or relatively to another object of the scene.

Object entities belong to the currently bound scene when generated. Upon deletion of a scene, all objects it contains are deleted.

void rtDeleteObjects	(	rtint	count,
		rtint *	names
	)

Delete object names.

Parameters:

	count	Specifies the number of objects to be deleted.
	names	Specifies an array of object names to be deleted.

rtDeleteObjects() deletes count objects named by the elements of the array names. After an object is deleted, its name is free for reuse by rtGenObjects(). If an object that is currently bound is deleted, the object binding becomes invalid.

rtDeleteObjects() skips names that do not correspond to existing objects, setting the error flag to RT_INVALID_NAME.

Object entities belong to the currently bound scene when generated. Upon deletion of a scene, all objects it contains are deleted.

void rtAttachModel ( rtint name )

Attach a model to object.

Parameters:

name

Specifies the name of the model to attach.

rtAttachModel() attaches the model identified by name to the currently bound object. Attempting to attach an invalid model name sets the error flag to RT_INVALID_NAME but preserves the previously attached model. By default, objects are not attached to any model.

Attaching a model to an object can expose the model's geometry if the object is present within its scene. The matrix of the object defines the position and orientation of the geometry relatively to its parent during ray-tracing operations.

The symbolic constant RT_DETACH can be used for the parameter name to indicate that the object is to be detached from any model.

Models can not be modified or deleted when attached by any object.

void rtObjectValue ( void * value )

Assign a value to object.

Parameters:

value

Specifies the value to be assigned to the object.

rtObjectValue() assigns value to the currently bound object. This value can be used to uniquely identify objects intersected by rays, see rtCollectObjectValues(), rtBufferEnv() and rtRayCallback(). The default value for an object is zero.

All primitives of the groups that compose the model attached to the object will return the same object value. To uniquely identify primitives, the value of the primitives themselves should be used.

void rtCullFace ( rtint mode )

Set the object face culling mode.

Parameters:

mode

Specifies the name of the model to attach. RT_BACK, RT_FRONT and RT_NONE are accepted.

rtCullFace() sets the face culling mode for the currently bound object. As rays traverse the scene, no intersection is recorded for culled faces. The culling mode applies to the geometry of all groups that define the model attached to the object. By default, the culling mode of an object is set to RT_NONE.

The accepted constants for the parameter mode are :

RT_BACK: Back faces are culled. Faces with counter-clockwise vertex ordering are intersected by rays.
RT_FRONT: Front faces are culled. Faces with clockwise vertex ordering are intersected by rays.
RT_NONE: No face is culled, rays intersect both front and back faces. It is the default.

void rtLoadMatrixf ( float * m )

Define the matrix of object with single precision.

Parameters:

m

Specifies a pointer to a 4x4 matrix to be loaded.

rtLoadMatrixf() replaces the matrix of the currently bound object by m. The 4x4 matrix is stored in column-major order.

The sum of all the groups of a model define the geometry of the objects attached to it. The geometry is multipled by the matrix of the object to define its position and orientation within the space of the scene or the parent object.

The default matrix for objects is an identity matrix. Passing a zero pointer as m parameter loads an identity matrix for the object.

void rtLoadMatrixd ( double * m )

Define the matrix of object with double precision.

Parameters:

m

Specifies a pointer to a 4x4 matrix to be loaded.

rtLoadMatrixd() replaces the matrix of the currently bound object by m. The 4x4 matrix is stored in column-major order.

The sum of all the groups of a model define the geometry of the objects attached to it. The geometry is multipled by the matrix of the object to define its position and orientation within the space of the scene or the parent object.

The default matrix for objects is an identity matrix. Passing a zero pointer as m parameter loads an identity matrix for the object.

void rtSetParent ( rtint name )

Set parent of object within the scene.

Parameters:

name

Specifies the name of the object to set as parent or one of the two symbolic constants RT_ABSENT and RT_ROOT.

rtSetParent() sets the parent of the currently bound object to the object identified by name. The name parameter can also be one of two symbolic constants RT_ABSENT or RT_ROOT.

The RT_ABSENT constant specifies that the object is absent from the scene. This is the default for newly generated objects. The RT_ROOT constant specifies that the object is the root object of the scene. There can only be one root object per scene and an existing root object has to be removed prior to specifying a new one.

Attempting to assign an invalid object name as parent sets the error flag to RT_INVALID_NAME but preserves the previously assigned parent. When an object is deleted, its child objects, if any, are marked as absent.

The sum of all the groups of a model define the geometry of the objects attached to it. The geometry is multipled by the matrix of the object to define its position and orientation within the space of the scene or the parent object.

void rtGenSources	(	rtint	count,
		rtint *	names
	)

Generate source names.

Parameters:

	count	Specifies the number of sources to be generated.
	names	Specifies an array in which the generated source names are stored.

rtGenSources() returns count source names in names. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to rtGenSources().

Source names returned by a call to rtGenSources() are not returned by subsequent calls, unless they are first deleted with rtDeleteSources(). The generated sources are undefined, origins must be specified prior to use in ray tracing operations.

Source entities belong to the currently bound scene when generated. Upon deletion of a scene, all sources it contains are deleted.

void rtBindSource ( rtint name )

Bind a source name.

Parameters:

name

Specifies the name of the source to be bound.

rtBindSource() makes the source identified by name current. Attempting to bind an invalid source name sets the error flag to RT_INVALID_NAME but does not break the previous binding.

Sources hold a point in the space of a scene from which rays can be traced. The commands rtSetOriginf() and rtSetOrigind() can be used to specify the origin of a source or it can be defined to match the intersection point of rays with the scene. See rtSupplyEndSources() for more information.

Source entities belong to the currently bound scene when generated. Upon deletion of a scene, all sources it contains are deleted.

void rtDeleteSources	(	rtint	count,
		rtint *	names
	)

Delete source names.

Parameters:

	count	Specifies the number of sources to be deleted.
	names	Specifies an array of source names to be deleted.

rtDeleteSources() deletes count sources named by the elements of the array names. After a source is deleted, its name is free for reuse by rtGenSources(). If a source that is currently bound is deleted, the source binding becomes invalid.

rtDeleteSources() skips names that do not correspond to existing sources, setting the error flag to RT_INVALID_NAME.

Source entities belong to the currently bound scene when generated. Upon deletion of a scene, all sources it contains are deleted.

void rtSetOriginf ( float * origin )

Set origin for a ray source in single precision.

Parameters:

origin

Specifies a pointer to an array to a set of x, y and z coordinates.

rtSetOriginf() sets the coordinates of the currently bound source. Sources are points within the scene to serve as origin of rays. The coordinates provided are absolute to the scene and not relative to any object.

Unless source names are provided for each ray through the rtSupplySources() command, the currently bound source defines the origin of all rays when rtTraceRays() is called.

Rays can be displaced from the their respective sources, see rtSupplyDisplacements().

void rtSetOrigind ( double * origin )

Set origin for a ray source in double precision.

Parameters:

origin

Specifies a pointer to an array to a set of x, y and z coordinates.

rtSetOrigind() sets the coordinates of the currently bound source. Sources are points within the scene to serve as origin of rays. The coordinates provided are absolute to the scene and not relative to any object.

Unless source names are provided for each ray through the rtSupplySources() command, the currently bound source defines the origin of all rays when rtTraceRays() is called.

Rays can be displaced from the their respective sources, see rtSupplyDisplacements().

void rtGenBuffers	(	rtint	count,
		rtint *	names
	)

Generate buffer names.

Parameters:

	count	Specifies the number of buffers to be generated.
	names	Specifies an array in which the generated buffer names are stored.

rtGenBuffers() returns count buffer names in names. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to rtGenBuffers().

Buffer names returned by a call to rtGenBuffers() are not returned by subsequent calls, unless they are first deleted with rtDeleteBuffers(). The generated buffers are not attached to a model, contain an identity matrix, have a value of zero, have no parent and the culling mode is set to RT_NONE.

Buffer entities are global to the current context.

void rtBindBuffer ( rtint name )

Bind a buffer name.

Parameters:

name

Specifies the name of the buffer to be bound.

rtBindBuffer() makes the buffer identified by name current. Attempting to bind an invalid buffer name sets the error flag to RT_INVALID_NAME but does not break the previous binding.

Buffers are fundamental ray-tracing operation targets. They hold information on what ray attributes are provided and the location data is to be read from. When rtTraceRays() is executed, the parameters of the bound buffer also defines how ray-tracing results are returned. See the command rtBufferEnv() to define buffer environment parameters.

Buffer entities are global to the current context.

void rtDeleteBuffers	(	rtint	count,
		rtint *	names
	)

Delete buffer names.

Parameters:

	count	Specifies the number of buffers to be deleted.
	names	Specifies an array of buffer names to be deleted.

rtDeleteBuffers() deletes count buffers named by the elements of the array names. After a buffer is deleted, its name is free for reuse by rtGenBuffers(). If a buffer that is currently bound is deleted, the buffer binding becomes invalid.

rtDeleteBuffers() skips names that do not correspond to existing buffers, setting the error flag to RT_INVALID_NAME.

Buffer entities are global to the current context.

void rtBufferEnv	(	rtint	target,
		rtint	value,
		void *	data
	)

Set buffer environment parameters.

Parameters:

	target	Specifies an environment parameter.
	value	Specifies the value or mode to be assigned to the parameter.
	data	Specifies data to be assigned to the parameter.

rtBufferEnv() defines environment parameters used for ray-tracing operations on the currently bound buffer. The accepted constants for the target parameter are RT_COLLECTION_MODE, RT_SUPPLY_MASK, RT_COLLECTION_MASK, RT_RAY_FLAGS_MASK, RT_RAY_CALLBACK_TYPE and RT_RAY_TRANSLATION.

If target is RT_COLLECTION_MODE, the command modifies the collection mode of the buffer. This defines how results are returned when rtTraceRays() is executed. The mode is specified by the value parameter, either RT_BUFFER_COLLECTION or RT_RAY_CALLBACK. The parameter data is ignored.

When the RT_BUFFER_COLLECTION mode is used, results are stored at the addresses specified by buffer collection commands such as rtCollectHitCoords(). The RT_RAY_CALLBACK mode causes results to be returned through callback functions. See rtRayCallback() for more information. The default collection mode is RT_BUFFER_COLLECTION.

If target is RT_SUPPLY_MASK, the parameter value is a bitwise mask to indicate what ray attributes are provided for ray-tracing operations. Unless otherwise specified, the attributes will be read at the addresses provided to the buffer for all enabled fields of the bitwise mask. The parameter data is ignored. The default value bitwise mask is zero. The values for the bitwise mask are defined as follows :

RT_SUPPLY_VECTOR_BIT: Indicates ray vectors. See rtSupplyVectors().
RT_SUPPLY_TARGET_BIT: Indicates target coordinates for rays. It is ignored if the bit RT_SUPPLY_VECTOR_BIT is also defined. See rtSupplyTargets().
RT_SUPPLY_DISPLACEMENT_BIT: Indicates displacements from the origin of rays. See rtSupplyDisplacements().
RT_SUPPLY_SOURCE_BIT: Indicates source names to be read to define the origin of rays. See rtSupplySources().
RT_SUPPLY_ENDSOURCE_BIT: Indicates source names to update at intersection points. See rtSupplyEndSources().
RT_SUPPLY_FLAGS_BIT: Indicates ray flags. See rtSupplyFlags().
RT_SUPPLY_TRANSLATION_BIT: Indicates ray translation. See below.
RT_SUPPLY_GEN_VECTOR_GRID_BIT from the RT_EXT_GEN_VECTORS extension: Indicates automatic vector grid generation. The bits RT_SUPPLY_VECTOR_BIT and RT_SUPPLY_TARGET_BIT are ignored if also defined. See rtGenVectorGrid().

If target is RT_COLLECTION_MASK, the parameter value is a bitwise mask to indicate what results are to be returned by ray-tracing operations. For the RT_BUFFER_COLLECTION mode, results will be written at the addresses provided to the buffer for all enabled fields of the bitwise mask. If the collection mode is set to RT_RAY_CALLBACK, structure fields that were not specified in the bitwise mask contain undefined data. The parameter data must be zero. The default value bitwise mask is zero. The values for the bitwise mask are defined as follows :

RT_COLLECT_POINT_BIT: Indicates the coordinates of the intersection point. See rtCollectHitCoords().
RT_COLLECT_UV_BIT: Indicates the barycentric coordinates of the primitive intersected. See rtCollectUvCoords().
RT_COLLECT_PLANE_BIT: Indicates the plane equation of the surface at the intersection point. See rtCollectPlanes().
RT_COLLECT_HITVALUE_BIT: Indicates the value of the primitive intersected. See rtCollectHitValues().
RT_COLLECT_OBJECTVALUE_BIT: Indicates the value of the object intersected. See rtCollectObjectValues().
RT_COLLECT_HITDISTANCE_BIT: Indicates the distance of the end point from the ray origin. See rtCollectObjectValues().

If target is RT_RAY_FLAGS_MASK, value is a bitwise mask that defines the desired behavior for flags attributes supplied to rays. If the bit identified by the symbolic constant RT_FLAGS_SKIP_BIT of value is set, the implementation will skip rays identified by a flag where the bit RT_FLAGS_SKIP_BIT is set. For the RT_BUFFER_COLLECTION mode, this implies that results are undefined for skipped rays. For the RT_RAY_CALLBACK mode, callbacks are not executed for skipped rays. The parameter data must be zero. The default value bitwise mask is zero.

If target is RT_RAY_CALLBACK_TYPE, the parameter value defines the data type used for storage of floating point values for ray callbacks. The symbolic constants RT_FLOAT and RT_DOUBLE are accepted. See the rtRayCallback() command for more information. The default value is RT_FLOAT.

If target is RT_RAY_TRANSLATION, the parameter value defines the data type of the single floating point value to be read from data. The symbolic constants RT_FLOAT and RT_DOUBLE are accepted. If the RT_SUPPLY_TRANSLATION_BIT is defined in the supply mask of the buffer, all rays will be translated by the product of the translation constant and their respective vectors. The default translation is zero.

Buffer entities are global to the current context.

void rtSupplyVectors	(	rtint	stride,
		rtint	type,
		void *	pointer
	)

Provide ray vectors.

Parameters:

	type	Specifies the data type of the vectors. The symbolic constants RT_FLOAT and RT_DOUBLE are accepted.
	stride	Specifies the byte offset between cons

Rayforce™ 1.0.0 - libRT

Functions

Detailed Description

Function Documentation


Functions
void *	rtCreateContext (char engine, char requirements, char *parameters)
	Create a context.
void	rtBindContext (void *context)
	Bind a context.
void	rtDestroyContext (void *context)
	Destroy a context.
rtint	rtGetError ()
	Query error information.
char *	rtGetString (rtint target)
	Query various information global to the context.
void *	rtGetProcAddress (char *procname)
	Query address of a procedure for the context.
void	rtWait (rtint status)
	Wait for context status.
void	rtContextEnv (rtint target, rtint value, void *data)
	Set or query context environment parameters.
void	rtGenScenes (rtint count, rtint *names)
	Generate scene names.
void	rtBindScene (rtint name)
	Bind a scene name.
void	rtDeleteScenes (rtint count, rtint *names)
	Delete scene names.
void	rtTraceRays (rtint count, void value, void callback, void *asynccallback)
	Trace rays.
void	rtBuild ()
	Build or update scene.
void	rtGenGroups (rtint count, rtint *names)
	Generate group names.
void	rtBindGroup (rtint name)
	Bind a group name.
void	rtDeleteGroups (rtint count, rtint *names)
	Delete group names.
void	rtBegin ()
	Begin specifying the geometry of a group.
void	rtEnd ()
	End specifying the geometry of a group.
void	rtAddTrianglef (float v0, float v1, float v2, void value)
	Add a triangle with single precision.
void	rtAddTriangled (double v0, double v1, double v2, void value)
	Add a triangle with double precision.
void	rtGenModels (rtint count, rtint *names)
	Generate model names.
void	rtBindModel (rtint name)
	Bind model name.
void	rtDeleteModels (rtint count, rtint *names)
	Delete model names.
void	rtModelEnv (rtint target, rtint value, void *data)
	Set or query model environment parameters.
void	rtAddGroups (rtint count, rtint *names)
	Add a list of groups to model.
void	rtRemoveGroups (rtint count, rtint *names)
	Remove a list of groups from model.
void	rtClearModel ()
	Clear the list of groups of model.
void	rtGenObjects (rtint count, rtint *names)
	Generate object names.
void	rtBindObject (rtint name)
	Bind an object name.
void	rtDeleteObjects (rtint count, rtint *names)
	Delete object names.
void	rtAttachModel (rtint name)
	Attach a model to object.
void	rtObjectValue (void *value)
	Assign a value to object.
void	rtCullFace (rtint mode)
	Set the object face culling mode.
void	rtLoadMatrixf (float *m)
	Define the matrix of object with single precision.
void	rtLoadMatrixd (double *m)
	Define the matrix of object with double precision.
void	rtSetParent (rtint name)
	Set parent of object within the scene.
void	rtGenSources (rtint count, rtint *names)
	Generate source names.
void	rtBindSource (rtint name)
	Bind a source name.
void	rtDeleteSources (rtint count, rtint *names)
	Delete source names.
void	rtSetOriginf (float *origin)
	Set origin for a ray source in single precision.
void	rtSetOrigind (double *origin)
	Set origin for a ray source in double precision.
void	rtGenBuffers (rtint count, rtint *names)
	Generate buffer names.
void	rtBindBuffer (rtint name)
	Bind a buffer name.
void	rtDeleteBuffers (rtint count, rtint *names)
	Delete buffer names.
void	rtBufferEnv (rtint target, rtint value, void *data)
	Set buffer environment parameters.
void	rtSupplyVectors (rtint stride, rtint type, void *pointer)
	Provide ray vectors.
void	rtSupplyTargets (rtint stride, rtint type, void *pointer)
	Provide ray targets.
void	rtSupplySources (rtint stride, rtint *names)
	Provide source names.
void	rtSupplyDisplacements (rtint stride, rtint type, void *pointer)
	Provide ray displacements.
void	rtSupplyEndSources (rtint stride, rtint *names)
	Provide source names to set at ray end points.
void	rtSupplyFlags (rtint stride, rtint *flags)
	Provide ray flags.
void	rtCollectHitCoords (rtint stride, rtint type, void *pointer)
	Collect hit point coordinates.
void	rtCollectUvCoords (rtint stride, rtint type, void *pointer)
	Collect barycentric coordinates.
void	rtCollectHitValues (rtint stride, void *pointer)
	Collect values of intersected primitives.
void	rtCollectObjectValues (rtint stride, void *pointer)
	Collect values of intersected objects.
void	rtCollectPlanes (rtint stride, rtint type, void *pointer)
	Collect plane equations.
void	rtCollectHitDistances (rtint stride, rtint type, void *pointer)
	Collect distances from origin to hit points.
void	rtRayCallback (rtint target, void *callback)
	Set ray callback functions.