VRAY_Procedural Class Reference

Procedural primitive for mantra (VRAY). More...

#include <VRAY_Procedural.h>

Inheritance diagram for VRAY_Procedural:

List of all members.

Public Member Functions
	VRAY_Procedural ()
virtual	~VRAY_Procedural ()
virtual const char *	getClassName ()=0
virtual int	initialize (const UT_BoundingBox *box)=0
virtual void	getBoundingBox (UT_BoundingBox &box)=0
	The bounding box is the "object space" bounds of the procedural.
virtual bool	isThreadSafe () const
virtual void	render ()=0
int	lookupParmToken (const char *name)
const int *	getIParm (const char *name) const
const fpreal *	getFParm (const char *name) const
const char **	getSParm (const char *name) const
const int *	getIParm (int token) const
const fpreal *	getFParm (int token) const
const char **	getSParm (int token) const
bool	import (const char *name, int *value, int vectorsize)
bool	import (const char *name, fpreal32 *value, int vectorsize)
bool	import (const char *name, fpreal64 *value, int vectorsize)
bool	import (const char *name, UT_String &result, int idx=0)
bool	import (void *handle, const char *name, int *value, int vectorsize)
bool	import (void *handle, const char *name, fpreal32 *value, int vectorsize)
bool	import (void *handle, const char *name, fpreal64 *value, int vectorsize)
bool	import (void *handle, const char *name, UT_String &result, int idx=0)
Protected Member Functions
GU_Detail *	allocateGeometry ()
void	freeGeometry (GU_Detail *gdp)
void	referenceGeometry (GU_Detail *gdp)
fpreal	getLevelOfDetail (const UT_BoundingBox &box)
void	openGeometryObject ()
void	addGeometry (GU_Detail *gdp, fpreal shutter)
float	addVelocityBlurGeometry (GU_Detail *gdp, fpreal shutter, const char *velocity_attribute="v")
int	openProceduralObject ()
void	addProcedural (VRAY_Procedural *proc)
int	addProcedural (int argc, char *argv[], const UT_BoundingBox *box=0)
void	openVolumeObject ()
	Open a volume object.
void	addVolume (VGEO_Volume *volume, fpreal shutter)
	Add a volume primitive to the currently open volume object.
void	setTransform (const UT_Matrix4 &transform, fpreal shutter)
void	closeObject ()
void *	queryObject (const char *name)
int	queryTransformSamples (void *object_handle)
const UT_Matrix4 &	queryTransform (void *object_handle, int sample)
const UT_Matrix4 &	queryShaderTransform (void *object_handle, int sample)
const char *	queryObjectName (void *handle)
const char *	queryRootName ()
	Get the name of the object which owns this procedural.
int	queryGeometrySamples (void *object_handle)
const GU_Detail *	queryGeometry (void *object_handle, int sample)
bool	changeSetting (const char *name, const char *value, const char *style="object")
bool	changeSetting (const char *name, int argc, char **argv, const char *style="object")
bool	changeSetting (const char *name, int argc, const int *argv, const char *style="object")
bool	changeSetting (const char *name, int argc, const fpreal *argv, const char *style="object")
Friends
class	VRAY_Instance
class	VRAY_Scene
class	VRAY_ProcDef

---

Detailed Description

Procedural primitive for mantra (VRAY).

The VRAY_Procedural class provides a means to create procedural geometry during the rendering process.

Examples:

VRAY/VRAY_DemoBox.C, VRAY/VRAY_DemoBox.h, VRAY/VRAY_DemoFile.C, VRAY/VRAY_DemoFile.h, VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoMountain.h, VRAY/VRAY_DemoSprite.C, VRAY/VRAY_DemoSprite.h, VRAY/VRAY_DemoStamp.C, VRAY/VRAY_DemoStamp.h, VRAY/VRAY_DemoVolumeSphere.C, and VRAY/VRAY_DemoVolumeSphere.h.

Definition at line 134 of file VRAY_Procedural.h.

---

Constructor & Destructor Documentation

VRAY_Procedural::VRAY_Procedural

(

)

virtual VRAY_Procedural::~VRAY_Procedural

(

)

[virtual]

---

Member Function Documentation

void VRAY_Procedural::addGeometry	(	GU_Detail *	gdp,
		fpreal	shutter
	)			[protected]

Before adding the geometry, you can change geometry settings by calling changeSettings(). For example, if you want to force computation of N, you can call: changeSetting("computeN", "true", "geometry"); This needs to be done BEFORE the addGeometry() call is made. Object settings can be changed after the geometry has been added.

Examples:

VRAY/VRAY_DemoBox.C, VRAY/VRAY_DemoFile.C, VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoSprite.C, and VRAY/VRAY_DemoStamp.C.

int VRAY_Procedural::addProcedural	(	int	argc,
		char *	argv[],
		const UT_BoundingBox *	box = 0
	)			[protected]

Add a procedural the the opened procedural object. This method allows you to create any registered procedural by passing argc and argv arguments to initialize the procedural.

Returns:

0 or 1 for failure/success

See also:

openProceduralObject()

void VRAY_Procedural::addProcedural

(

VRAY_Procedural *

proc

)

[protected]

Add a procedural to the opened procedural object. Use this method when allocating a "private" procedural (i.e. a procedural object which isn't registered with mantra).

See also:

openProceduralObject()

Examples:

VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoSprite.C, and VRAY/VRAY_DemoStamp.C.

float VRAY_Procedural::addVelocityBlurGeometry	(	GU_Detail *	gdp,
		fpreal	shutter,
		const char *	velocity_attribute = "v"
	)			[protected]

If you want to perform velocity motion blur on the geometry, you can add all the detail at once, calling this convenience function. Note: The "shutter" is really a scale on the velocity. However, since velocity is typically specified in units/second, you usually need to scale by the shutter time of the frame. To do this, you should multiply by the "object:velocityscale" property of the object.

Assume that we have a procedural where the user can specify an individual shutter time in a parameter called "shutter". Then, the initialization code might look something like:

         float   shutter, vscale;
         if (!import("shutter", &shutter, 1))
                 shutter = 1;    // Default to full shutter
         if (!import("object:velocityscale", &vscale, 1))
         {
                 // This should never happen since it's a property
                 vscale = 0;
         }
         this->myShutter = shutter * vscale;

Then, during the rendering process:

         gdp = allocateGeometry();
         createGeometry(gdp);    // Create the render geometry
         addGeometry(gdp, 0);    // Add geometry for beginning of frame
         // Add the motion blur geometry
         addVelocityBlurGeometry(gdp, this->myShutter);

The maximum velocity displacement is returned (so that bounding boxes may be computed).

Examples:

VRAY/VRAY_DemoFile.C.

void VRAY_Procedural::addVolume	(	VGEO_Volume *	volume,
		fpreal	shutter
	)			[protected]

Add a volume primitive to the currently open volume object.

Examples:

VRAY/VRAY_DemoVolumeSphere.C.

GU_Detail* VRAY_Procedural::allocateGeometry

(

)

[protected]

Warning:

Mantra uses a sub-class of GU_Detail. It is imperative that all geometry to be rendered be allocated and free'd using the following methods. Otherwise, crashes will ensue.

Examples:

VRAY/VRAY_DemoBox.C, VRAY/VRAY_DemoFile.C, VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoSprite.C, and VRAY/VRAY_DemoStamp.C.

bool VRAY_Procedural::changeSetting	(	const char *	name,
		int	argc,
		const fpreal *	argv,
		const char *	style = "object"
	)			[protected]

Change any setting on the object (geometry, procedural, volume)

• changeSetting(const char *name, const char *value)
  Parses the string into arguments and changes the setting If you want to change a setting to a single string value, it is better to call: changeSettings(name, 1, &value);
• changeSetting(const char *name, int argc, char **argv)
• changeSetting(const char *name, int argc, int *argv)
• changeSetting(const char *name, int argc, fpreal *argv) If the setting specified by "name" isn't found, the function will fail (return false).

bool VRAY_Procedural::changeSetting	(	const char *	name,
		int	argc,
		const int *	argv,
		const char *	style = "object"
	)			[protected]

Change any setting on the object (geometry, procedural, volume)

• changeSetting(const char *name, const char *value)
  Parses the string into arguments and changes the setting If you want to change a setting to a single string value, it is better to call: changeSettings(name, 1, &value);
• changeSetting(const char *name, int argc, char **argv)
• changeSetting(const char *name, int argc, int *argv)
• changeSetting(const char *name, int argc, fpreal *argv) If the setting specified by "name" isn't found, the function will fail (return false).

bool VRAY_Procedural::changeSetting	(	const char *	name,
		int	argc,
		char **	argv,
		const char *	style = "object"
	)			[protected]

Change any setting on the object (geometry, procedural, volume)

• changeSetting(const char *name, const char *value)
  Parses the string into arguments and changes the setting If you want to change a setting to a single string value, it is better to call: changeSettings(name, 1, &value);
• changeSetting(const char *name, int argc, char **argv)
• changeSetting(const char *name, int argc, int *argv)
• changeSetting(const char *name, int argc, fpreal *argv) If the setting specified by "name" isn't found, the function will fail (return false).

bool VRAY_Procedural::changeSetting	(	const char *	name,
		const char *	value,
		const char *	style = "object"
	)			[protected]

Change any setting on the object (geometry, procedural, volume)

• changeSetting(const char *name, const char *value)
  Parses the string into arguments and changes the setting If you want to change a setting to a single string value, it is better to call: changeSettings(name, 1, &value);
• changeSetting(const char *name, int argc, char **argv)
• changeSetting(const char *name, int argc, int *argv)
• changeSetting(const char *name, int argc, fpreal *argv) If the setting specified by "name" isn't found, the function will fail (return false).

Examples:

VRAY/VRAY_DemoBox.C.

void VRAY_Procedural::closeObject

(

)

[protected]

After all geometry, procedurals, volumes have been added and all the attributes have been set, the object can be closed.

Examples:

VRAY/VRAY_DemoBox.C, VRAY/VRAY_DemoFile.C, VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoSprite.C, VRAY/VRAY_DemoStamp.C, and VRAY/VRAY_DemoVolumeSphere.C.

void VRAY_Procedural::freeGeometry

(

GU_Detail *

gdp

)

[protected]

Normally freeGeometry() should never be called since you'll usually use allocateGeometry() to create a new geometry that is later passed off to the procedural using addGeometry(). However, if you need to keep a reference to the geometry using referenceGeometry() it is possible to free or clear the reference using freeGeometry(). freeGeometry() may also be used to deallocate geometry that was never passed off with addGeometry().

Examples:

VRAY/VRAY_DemoFile.C, and VRAY/VRAY_DemoSprite.C.

virtual void VRAY_Procedural::getBoundingBox

(

UT_BoundingBox &

box

)

[pure virtual]

The bounding box is the "object space" bounds of the procedural.

Implemented in VRAY_ProcIsoBase, HDK_Sample::VRAY_DemoBox, HDK_Sample::VRAY_DemoFile, HDK_Sample::VRAY_DemoMountain, HDK_Sample::VRAY_DemoSprite, HDK_Sample::vray_ChildBox, HDK_Sample::VRAY_DemoStamp, and HDK_Sample::VRAY_DemoVolumeSphere.

virtual const char* VRAY_Procedural::getClassName

(

)

[pure virtual]

The class name is used in diagnostic messages. It can simply be the name of the class, or alternatively, you can choose a unique name for each procedural instance.

Implemented in VRAY_ProcIsoBase, HDK_Sample::VRAY_DemoBox, HDK_Sample::VRAY_DemoFile, HDK_Sample::VRAY_DemoMountain, HDK_Sample::VRAY_DemoSprite, HDK_Sample::vray_ChildBox, HDK_Sample::VRAY_DemoStamp, and HDK_Sample::VRAY_DemoVolumeSphere.

const fpreal* VRAY_Procedural::getFParm

(

int

token

)

const

Get the raw data pointers for a parameter by either name or value.

See also:

import()

const fpreal* VRAY_Procedural::getFParm

(

const char *

name

)

const

Get the raw data pointers for a parameter by either name or value.

See also:

import()

const int* VRAY_Procedural::getIParm

(

int

token

)

const

Get the raw data pointers for a parameter by either name or value.

See also:

import()

const int* VRAY_Procedural::getIParm

(

const char *

name

)

const

Get the raw data pointers for a parameter by either name or value.

See also:

import()

fpreal VRAY_Procedural::getLevelOfDetail

(

const UT_BoundingBox &

box

)

[protected]

This method allows you to compute the level of detail of an arbitrary bounding box. The shading_quality parameter is a multiplier on the computed level of detail. Higher shading_qalities will result in higher level of details.

Examples:

VRAY/VRAY_DemoMountain.C, and VRAY/VRAY_DemoSprite.C.

const char** VRAY_Procedural::getSParm

(

int

token

)

const

Get the raw data pointers for a parameter by either name or value.

See also:

import()

const char** VRAY_Procedural::getSParm

(

const char *

name

)

const

Get the raw data pointers for a parameter by either name or value.

See also:

import()

bool VRAY_Procedural::import	(	void *	handle,
		const char *	name,
		UT_String &	result,
		int	idx = 0
	)

If you've opened an object handle using queryObject(), it's possible to query the settings of that object. This makes it possible to query the parameters/values/settings of other objects in the scene.

bool VRAY_Procedural::import	(	void *	handle,
		const char *	name,
		fpreal64 *	value,
		int	vectorsize
	)

If you've opened an object handle using queryObject(), it's possible to query the settings of that object. This makes it possible to query the parameters/values/settings of other objects in the scene.

bool VRAY_Procedural::import	(	void *	handle,
		const char *	name,
		fpreal32 *	value,
		int	vectorsize
	)

If you've opened an object handle using queryObject(), it's possible to query the settings of that object. This makes it possible to query the parameters/values/settings of other objects in the scene.

bool VRAY_Procedural::import	(	void *	handle,
		const char *	name,
		int *	value,
		int	vectorsize
	)

If you've opened an object handle using queryObject(), it's possible to query the settings of that object. This makes it possible to query the parameters/values/settings of other objects in the scene.

bool VRAY_Procedural::import	(	const char *	name,
		UT_String &	result,
		int	idx = 0
	)

The import functions can be used as a general purpose query mechanism. This will import values from:

• The argument list for the procedural
• The argument list for the object defining the procedural
• A global rendering setting. Aside from a parameter name, the name could be "object:name", "object:shadingquality", "camera:pixelaspect", or any of the other setting defined in mantra.

bool VRAY_Procedural::import	(	const char *	name,
		fpreal64 *	value,
		int	vectorsize
	)

The import functions can be used as a general purpose query mechanism. This will import values from:

• The argument list for the procedural
• The argument list for the object defining the procedural
• A global rendering setting. Aside from a parameter name, the name could be "object:name", "object:shadingquality", "camera:pixelaspect", or any of the other setting defined in mantra.

bool VRAY_Procedural::import	(	const char *	name,
		fpreal32 *	value,
		int	vectorsize
	)

The import functions can be used as a general purpose query mechanism. This will import values from:

• The argument list for the procedural
• The argument list for the object defining the procedural
• A global rendering setting. Aside from a parameter name, the name could be "object:name", "object:shadingquality", "camera:pixelaspect", or any of the other setting defined in mantra.

bool VRAY_Procedural::import	(	const char *	name,
		int *	value,
		int	vectorsize
	)

The import functions can be used as a general purpose query mechanism. This will import values from:

• The argument list for the procedural
• The argument list for the object defining the procedural
• A global rendering setting. Aside from a parameter name, the name could be "object:name", "object:shadingquality", "camera:pixelaspect", or any of the other setting defined in mantra.

virtual int VRAY_Procedural::initialize

(

const UT_BoundingBox *

box

)

[pure virtual]

The initialize method is called when the procedural is created. Returning zero (failure) will abort the rendering of this procedural.

The bounding box passed in is the user defined bounding box. If the user didn't specify a bounding box, then the box will be NULL.

Implemented in VRAY_ProcIsoBase, HDK_Sample::VRAY_DemoBox, HDK_Sample::VRAY_DemoFile, HDK_Sample::VRAY_DemoMountain, HDK_Sample::VRAY_DemoSprite, HDK_Sample::vray_ChildBox, HDK_Sample::VRAY_DemoStamp, and HDK_Sample::VRAY_DemoVolumeSphere.

virtual bool VRAY_Procedural::isThreadSafe

(

)

const [inline, virtual]

Returns true when the render() method of this procedural is thread-safe - that is, the render() method on different VRAY_Procedural objects can be called simultaneously by different threads. By default, procedurals are assumed to thread unsafe.

Definition at line 158 of file VRAY_Procedural.h.

int VRAY_Procedural::lookupParmToken

(

const char *

name

)

The getParm() methods evaluate parameters attached to the procedural. The lookup may be performed by name or by token. Each parameter has a unique token associated with it. The token lookup methods are more efficient than the name lookups and should be almost as efficient as accessing member data. Parameters to the procedural are stored as a list of VRAY_ProceduralArg objects. Each parameter is given a unique integer. This allows for more efficient evaluation (avoiding comparing strings).

void VRAY_Procedural::openGeometryObject

(

)

[protected]

When the render method is called, the procedural can add objects to the scene. It is possible for the render() method to add multiple objects.

The process for adding a geometry object:

• open a geometry object (openGeometryObject())
• add geometry to the object (addGeometry())
• modify any settings (changeSetting())
• close the object (closeObject())

The process for adding a new procedural is fairly similar:

• open a procedural object (openProcecuralObject())
• add procedural(s) to the object (addProcedural())
• modify any settings (changeSetting())
• close the object (closeObject())

For a geometry object, deformation motion blur is done by adding multiple geometry objects.

If settings are not overridden by the procedural, they will be inherited from the object defining the procedural.

The shutter time should be between 0 and 1.

The renderer assumes ownership of any geometry or procedurals written to objects. Thus, the geometry and procedurals should not be free'd by the user.

Examples:

VRAY/VRAY_DemoBox.C, VRAY/VRAY_DemoFile.C, VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoSprite.C, and VRAY/VRAY_DemoStamp.C.

int VRAY_Procedural::openProceduralObject

(

)

[protected]

If the procedural has been split too many times, it will not be possible to generate further procedurals. This can happen if the procedural is centered around the origin (i.e. cuts the camera clipping plane) and hasn't shrunk itself enough to isolate itself.

Examples:

VRAY/VRAY_DemoMountain.C, VRAY/VRAY_DemoSprite.C, and VRAY/VRAY_DemoStamp.C.

void VRAY_Procedural::openVolumeObject

(

)

[protected]

Open a volume object.

Examples:

VRAY/VRAY_DemoVolumeSphere.C.

const GU_Detail* VRAY_Procedural::queryGeometry	(	void *	object_handle,
		int	sample
	)			[protected]

Get the geometry from another object

See also:

queryObject()

Examples:

VRAY/VRAY_DemoSprite.C.

int VRAY_Procedural::queryGeometrySamples

(

void *

object_handle

)

[protected]

Find out how many geometry samples associated with the object.

See also:

queryObject()

void* VRAY_Procedural::queryObject

(

const char *

name

)

[protected]

It is possible to query information about other objects in the scene to some extent. This is done using the following query methods. Find a handle to a given object in the scene. Note that for objects which are rendered using point instances, the object handle will be a single instance rather than all of the instances. If a null pointer is passed in for the name, then the object refers to the object containing this procedural. The object handle does not need to be closed.

Examples:

VRAY/VRAY_DemoSprite.C.

const char* VRAY_Procedural::queryObjectName

(

void *

handle

)

[protected]

Find out the name of the object queried. This is useful when trying to find out which object the procedural belongs to (i.e. queryObject(0))

See also:

queryObject()

Examples:

VRAY/VRAY_DemoSprite.C.

const char* VRAY_Procedural::queryRootName

(

)

[protected]

Get the name of the object which owns this procedural.

Examples:

VRAY/VRAY_DemoSprite.C.

const UT_Matrix4& VRAY_Procedural::queryShaderTransform	(	void *	object_handle,
		int	sample
	)			[protected]

Get the shading transform associated with an object in the scene

See also:

queryObject()

const UT_Matrix4& VRAY_Procedural::queryTransform	(	void *	object_handle,
		int	sample
	)			[protected]

Get the transform associated with an object in the scene

See also:

queryObject()

Examples:

VRAY/VRAY_DemoSprite.C.

int VRAY_Procedural::queryTransformSamples

(

void *

object_handle

)

[protected]

Query the number of transform samples for a given query object

See also:

queryObject()

void VRAY_Procedural::referenceGeometry

(

GU_Detail *

gdp

)

[protected]

This method allows a single geometry object to be added multiple times with addGeometry(). For each addGeometry() operation, first call referenceGeometry() to allow the caller to keep a reference to the geometry, then use freeGeometry() to release the referenced geometry when you're done with it. For example:

         GU_Detail       *gdp;
         // Allocate the geometry
         gdp = allocateGeometry();
         // Create 2 instances of the geometry.  Normally these
         // should be created with differing transforms.
         referenceGeometry(gdp);
         addGeometry(gdp);
         referenceGeometry(gdp);
         addGeometry(gdp);
         // Unreference the local copy
         freeGeometry(gdp);

virtual void VRAY_Procedural::render

(

)

[pure virtual]

The render method is called when the procedural is required to either generate geometry or split into more procedurals. The level of detail passed in represents the rough screen space projection of the procedural's bounding box. The value is roughly the number of pixels that the bounding box occupies (modified by the LEVEL OF DETAIL rate).

For example, if a box occupies 10 horizontal pixels and 20 vertical pixels, the lod passed in will be roughly 20 (the maximum bounds occupied in screen space). If the object surrounds the camera, the lod will be clamped at a large number.

Note:

The render method may be called more than once during a render to regenerate the geometry.

Implemented in VRAY_ProcIsoBase, HDK_Sample::VRAY_DemoBox, HDK_Sample::VRAY_DemoFile, HDK_Sample::VRAY_DemoMountain, HDK_Sample::VRAY_DemoSprite, HDK_Sample::vray_ChildBox, HDK_Sample::VRAY_DemoStamp, and HDK_Sample::VRAY_DemoVolumeSphere.

void VRAY_Procedural::setTransform	(	const UT_Matrix4 &	transform,
		fpreal	shutter
	)			[protected]

Transform the currently open object (geometry, procedural, volume) at the shutter time specified.

---

Friends And Related Function Documentation

friend class VRAY_Instance [friend]

Definition at line 524 of file VRAY_Procedural.h.

friend class VRAY_ProcDef [friend]

Definition at line 526 of file VRAY_Procedural.h.

friend class VRAY_Scene [friend]

Definition at line 525 of file VRAY_Procedural.h.

---

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

• VRAY/VRAY_Procedural.h