V-Ray architecture

This article describes most of the classes needed to work with the V-Ray SDK in order to create a renderer based on the V-Ray API. An example of the usage for almost all of these can be found in the "renderer" sample in the \samples\renderer folder of the V-Ray SDK.

 

Rendering with V-Ray

Setting up the sequence data

The RegionDoneCallback class

Setting up the frame data

V-Ray implementations

Deriving from class VRayRenderer

Derivnig from class VRayPluginRenderer

Image sampling

Generating geometry

Shading

V-Ray API calls sequence

Implementing distributed rendering

Rendering with V-Ray

In its most basic form, rendering with V-Ray goes through several phases:

A specific V-Ray implementation is represented by an instance of a class derived from class VRayRenderer. This class has methods beginSequence(), beginFrame(), renderImage(), endFrame and endSequence(). Those methods directly correspond to the phases above. So, if we want to render a sequence of frames, given an instance of class VRayRenderer, it should be done like this:

 

// Renders a sequence of frames, given a vray implementation

void renderSequence(VR::VRayRenderer *vray, int startFrame, int endFrame) {

VR::VRaySequenceData &sequenceData=getSequenceData(vray, startFrame, endFrame);

vray->beginSequence(sequenceData);

 

for (int frame=startFrame; i<endFrame; i++) {

VR::VRayFrameData &frameData=getFrameData(vray, frame);

vray->beginFrame(frameData);

 

VR::VRayImageData &imageData=getImageData(vray);

vray->renderImage(imageData);

 

vray->endFrame();

}

 

vray->endSequence();

}

 

Note that there are some additional structures used, VRaySequenceData and VRayFrameData. These structures are very important as they specify the various parameters for the rendering (things like AA, global illumination algorithms in VRaySequenceData; current frame time, camera transformation etc in VRayFrameData). During rendering, these structures can be accessed from a pointer to class VRayRenderer through VRayRenderer::getSequenceData() and VRayRenderer::getFrameData(). For example, you will need to access these structures when generating the scene geometry in order to determine if motion blur is on, so that the correct geometry type can be generated.

Setting up the sequence data

Here is an example for setting up the sequence data; note that only the regionDoneCallback is required, the other members can be NULL, although usually you will want to override them with your own (for example, you will have to pass a directLightManager, if you want to have any lights in the scene).

 

VR::VRaySequenceData& getSequenceData(VR::VRayRenderer *vray, int startFrame, int endFrame) {

static VR::VRaySequenceData sdata;

 

// Set the sequence data to default values

sdata.setDefaults();

 

// Set additional sequence data parameters

sdata.animStart=startFrame;
sdata.animEnd=endFrame;
sdata.regionDoneCallback=doneCallback;

return sdata;

}

 

If you are using class VRayPluginRenderer to derive your V-Ray implementation, you can use the various SettingsXXXX plugins to set up some specific V-Ray parameters (the GI engines used etc) instead of changing this strucure directly.

The RegionDoneCallback class

A pointer to an instance of class RegionDoneCallback must be passed in the sequence data; this class tells V-Ray what to do with the rendered output. This class also handles all the output channels. The default V-Ray VFB can provide an instance of this classes for rendering to the VFB. If the default VFB is not used, you must provide this callback yourself.

 

V-Ray computes the image by taking a number of image samples, and then computing the final image pixels from them. This process is performed by instances of class ImageSampler. V-Ray has three built-in image samplers (fixed rate, adaptive dmc and adaptive image subdivision).

 

Regradless of which ImageSampler is used, each image sample is represented by an instance of class FragmentList and can be split into multiple Fragments that carry information for several image channels. For example, in V-Ray for 3dsmax, a single image sample carries information about all the objects in the scene that contribute to that sample, as well as their specific contribution. The sample also contains information about the combined contribution of all fragments. This information is used to fill the extended 3dsmax G-Buffer.

 

In a simple V-Ray implementation, an image sample (FragmentList) would consist of a single Fragment, containting the color for the image at the specific image point.

 

See the Image sampling section below for more detail.

Setting up the frame data

This is somewhat more complicated, since it also requires setting up of camera transformation matrices, output image resolution etc. See the sample renderer included with the V-Ray SDK for more details on this.

 

VR::VRayFrameData& getFrameData(VR::VRayRenderer *vray, int frame) {

static VR::VRayFrameData fdata;

 

fdata.t=frame;

 

// Set the various members of fdata

// ...

 

return fdata;

}

 

If you are deriving your V-Ray implementation from class VRayPluginRenderer, you can also use the various SettingsXXXX or RenderView plugins to set up parts of this structure.

V-Ray implementations

Note that you can't use the VRayRenderer class directly; instead, you need to derive from it to get a particular V-Ray implementation. You can either derive your renderer class directly from VRayRenderer, or instead derive it from VRayPluginRenderer.

Deriving directly from class VRayRenderer

Deriving from VRayRenderer directly is done when you do not want to use V-Ray plugins to describe the scene and instead operate directly with the V-Ray API. An example for such an implementation is V-Ray for 3ds Max.

 

class MyVRay: public VR::VRayRenderer {

public:

// Notifications

void renderBegin(void);

void renderEnd(void);

void frameBegin(void);

void frameEnd(void);

void imageBegin(void);

void imageEnd(void);

 

// Geometry handling

void compileGeometry(void);

void clearGeometry(void);

 

// Output handling

void setResult(VR::VRayContext &rc, VR::Color &fgColor, VR::Color &bgColor);

};

 

Except for the compileGeometry() and clearGeometry() methods, implementing the other methods is not necessary, but is usually a good idea. V-Ray calls these methods during the various stages of the rendering process (for example, renderBegin() is called when you call VRayRenderer::beginSequence(), frameBegin() is called when you call VRayRenderer::beginFrame() etc). You can use these methods to compute any additional stuff required for the entire sequence (for example, loading bitmap files) or for the particular frame (for example, loading a particular frame from an animated texture bitmap, or performing a dynamics simulation to compute object positions for that frame).

 

The most important method of these is compileGeometry(). V-Ray will call this in the beginning of every frame. The purpose of this method is compute the geometry in the scene, and pass this geometry to the V-Ray ray server, so that it can be used for raycasting during the actual rendering. Typically, this methods looks like this:

 

void MyVRay::compileGeometry(void) {

// Get a pointer to the ray server

VR::RayServerInterface *rayserver=getRayServer();

 

// Go through all objects in the scene

for (int i=0; i<objects.count(); i++) {

// Put the geometry of the i-th object into the ray server

objects[i]->myCompileGeometry(rayserver);

}

}

 

There are several geometry types that the ray server can deal with. The simplest ones are static triangles. You can also define your own geometric primitives.

 

For more information on geometry generation, see the Generating geometry section below .

 

The clearGeometry() method is called at the end of each frame, after all the data associated with the ray server has been freed. This allows you to free any additional memory associated with the scene objects (for example, vertex normals etc).

 

The setResult() method is also important, since it is responsible for storing the final ray result from a camera ray into the FragmentList for the given VRayContext. A simple implementation would be like this:

 

void MyVRay::setResult(VR::VRayContext &rc, VR::Color &fgColor, VR::Color &bgColor) {

// Get the Fragment for the final result

MyFragment *frag=(MyFragment*) rc.getCurrentGBufferFragment();

 

// Set the color of the fragment

if (frag) frag->color=rc.shaderesult.color;

}

 

In addition to the ray color, you can store any other value of interest here, for example, you can store z-depth information, alpha transparency etc. The ImageSampler will combine the sub-pixel values into a pixel FragmentList and pass it to the OutputRegion returned by RegionDoneCallback.

Deriving from class VRayPluginRenderer

Instead of deriving from class VRayRenderer directly, you can use class VRayPluginRenderer. The latter one operates on a list of plugins and automates a large part of the rendering process - e.g. it provides a default direct light manager, compiles all the geometry from the corresponding plugins etc. It also allows the usage of any of the available V-Ray plugins for geometry, materials, lights etc. V-Ray for Maya and V-Ray Standalone both use renderers derived from class VRayPluginRenderer.

 

Image sampling

This topic discusses how image sampling is performed in V-Ray, and which classes are involved.

 

When VRayRenderer::renderImage() is called, V-Ray looks at the frame data to determine which part of the image must be computed. It then splits it into a number of rectangular regions (buckets).

 

For each rendering thread, V-Ray creates a separate OutputRegion class with a call to RegionDoneCallback::newOutput(). After rendering is complete, RegionDoneCallback::deleteOutput() is called to free it.

 

For each of the rendering buckets, V-Ray calls RegionDoneCallback::regionInit() to initialize it and passes it to the ImageSampler::sampleImage(), along with a default ImageFunction. The ImageSampler has the task of sampling the ImageFunction and calling OutputRegion::storeFragmentList() for each pixel in the bucket. After that, V-Ray calls RegionDoneCallback::regionDone(). This is repeated for all the buckets of the image.

 

The default ImageFunction created by V-Ray typically creates a camera ray, traces it into a VRayContext and passes it to VRayRenderer::setResult() which has the task of deriving the final image sample value from the VRayContext into a FragmentList.

Generating geometry

As described above, in the VRayRenderer::compileGeometry() method, you need to store the scene geometry into the ray server provided by V-Ray.

 

V-Ray supports various geometry types; here we will discuss only simple static triangles.

 

The ray server supports simple triangles through the RayServerInterface::storeStaticTriangle() method:

 

void MyGeometryGenerator::myCompileGeometry(VR::RayServerInterface *rayserver) {

for (int i=0; i<numTriangles; i++) {

VR::Vector p[3];

getTriangleVertices(i, p);

rayserver->storeStaticTriangle(this, i+shuffleIndex(renderID), p);

}

}

 

In addition to the triangle vertices, you need to pass a GeometryGenerator associated with each triangle, and a more or less unique primitive identifier.

 

The primitive identifier has two purposes. The first is to identify the primitive to the GeometryGenerator (that is, given a primitive identifier, the GeometryGenerator must be able to tell to which triangle it corresponds). The second purpose is to identify a single primitive that will be excluded from ray intersection checks. This is used to avoid "surface acne" - if a ray origin lies on a particular triangle, there is no need to check this triangle for intersection. In general, there is no good way to ensure the unique-ness of primitive identifiers, when we consider that we may have dynamic geometry which can be created and destroyed on the fly while rendering. This is why, in V-Ray, a randomized method is used (the shuffleIndex() function above). Usually the identifier of each primitive is its index plus the shuffled index of its parent.

 

The GeometryGenerator is reponsible for providing intersection information when a ray has been determined to intersect a triangle. Since each triangle stores only enough information to perform ray intersection with it, along with its GeometryGenerator, any additional information (like interpolated surface normal, for example) must be provided in the GeometryGenerator::setIntersectionData() method. When V-Ray has determined that a ray intersects a given triangle, it calls this method and passes a pointer to an IntersectionData structure, which must be filled with information about the intersection (hit point, barycentric coordinates, which shading procedure will be used etc):

 

void MyGeomGen::setIntersectionData(VR::RSRay &rsray, void *isd) {

VR::IntersectionData &isData=*((IntersectionData*) isd);
VR::RSIntersection &is=rsray.is;

 

VR::SimpleStaticTriangle *tri=(VR::SimpleStaticTriangle*) rsray.is.primitive;
int triangleIndex=tri->ownerIndex-shuffleIndex(renderID);

// Fill in the isData structure

// ...

 

// Set the Shadeable that will be called to shade the intersection

isData.sb=(Shadeable*) this;

}

Shading

The GeometryGenerator::setIntersectionData() method is also responsible for supplying a pointer to a Shadeable object that can be called to shade the intersection point. Typically, GeometryGenerator's also derive from Shadeable and so they set the sb pointer of the intersection data to this. When V-Ray needs to determine the radiance for a given ray (the amount of light reflected from the scene towards the ray origin), it calls the Shadeable::shade() method. This method must compute the surface color and store it in VRayContext::mtlresult.

 

Usually the Shadeable::shade() method calls a material to compute the surface color:

 

void MyGeomGen::shade(VR::VRayContext &rc) {

surfaceMaterial->shade(rc);

}

 

The material can use various BRDFs etc for this purpose. In general, shading can be broken in several components:

(1) Light that is directly reflected from light sources off the surface and into the direction of the ray origin:

(1.1) Direct light reflected diffusely;

(1.2) Direct light reflected specularly;

(2) Light that is indirectly reflected from other objects in the scene; this can be separated into:

(2.1) Light that is diffusely reflected by the surface;

(2.2) Light that is specularly reflected by the surface.

 

Different algorithms are suitable for each of these components and V-Ray uses different methods for their computation.

 

The BRDFSampler is a central class in V-Ray's shading subsystem. It describes how light is scattered at a given surface point. In general, V-Ray treats (2.1) as an additional light source that produces only diffuse illuminaton. There is a method, VRayContext::evalLight() which takes a BRDFSampler and computes (1.1), (1.2) and (2.1) together. This method cycles through all the lights in the scene, filters them through the BRDFSampler::eval() method and adds their contribution.

 

The (2.2) component is very specific to every BRDF and there is no general way to evaluate it efficiently. That is why each BRDFSampler has a traceForward() method, responsible for computing (2.2) - a mirror BRDF traces reflected rays, a glass BRDF traces refracted rays etc. This method also allows the simulation of BSSRDF - it may involve computing lighting at other points on the surface.

 

For example, a surface can be shaded like this:

 

void MyMaterial::shade(VR::VRayContext &rc) {

// Clear the current result

rc.mtlresult.clear();

 

// Get a new BTDF sampler for the intersection point

BTDFSampler *btdf=newBTDF(rc);

 

// Compute the lighting contribution

VR::Color directLight=rc.evalLight(*btdf);

 

// Trace the BRDF forward (reflections, refractions etc)

btdf->traceBTDFForward(rc, true);

 

// Add in light contribution
rc.mtlresult.color+=directLight;

// Delete the BRDF
deleteBTDF(rc, btdf);

}

 

As a convenience, the V-Ray API defines a plugin class BRDFShadeable, which will do the proper shading and only a BRDFSampler must be provided. It is a good idea to use this class, since it automatically provides support for the BRDFInterface interface, which is used by path tracing algorithms which operate on the surface BRDF directly.

V-Ray API calls sequence

As a reference, here is the typical sequence of API calls when rendering with V-Ray; calls between brackets '[' and ']' can be executed multiple times in a cycle; indented calls are made within the method they are under. Note that not all calls are listed, only the most important ones. This diagram may help understand where in the rendering process the different methods and classes are used.

 

VRayRenderer::beginSequence()
[
VRayRenderer::beginFrame()
VRayCamera::frameBegin()
VRayCameraSampler::frameBegin()
VRayRenderer::frameBegin()
VRayRenderer::compileGeometry()
RayServerInterface::build()
DirectLightManager::frameBegin()
GlobalLightManager::frameBegin()
RegionDoneCallback::frameBegin()
VRayRenderer::renderImage()
VRayRenderer::imageBegin()
RegionDoneCallback::imageBegin()
RegionDoneCallback::newOutput()
[
RegionDoneCallback::regionInit()
ImageSampler::sampleRegion()
OutputRegion::init()
[
VRayRenderer::ImageFunction::SampleImage()
VRayRenderer::getThreadData()
VRayThreadData::newVRayContext()
VRayContext::clear()
VRayRenderer::traceScreenRay()
VRayCameraSampler::traceCamera()
VRayCameraSampler::initRayContext()
VRayCamera::getScreenRay()
VRayCameraSampler::interpolateTimeRay()
VRayContext::setRay()
VRayCore::traceRay()
VRayThreadData::newRayID()
RayServerInterface::intersect()
[
GenericPrimitive::setIntersectionData()
VRayContext::setRayResult()
VRayCore::shadeRayResult()
VRayThreadData::newShadeID()
VRayVolume::shadeVolume()
VRayCore::computeAtmospherics()
VRayShadeable::shade()
VRayGlobalLightManager::evalLight()
DirectLightManager::eval()
]
VRayCore::computeEnvironment()
VRayCameraSampler::getBgColor()
VRayColorMapper::mapColor()
VRayContext::releaseContext()
VRayThreadData::releaseVRayContext()
OutputRegion::storeFragmentList()
]
OutputRegion::done()
RegionDoneCallback::regionDone()
]
RegionDoneCallback::deleteOutput()
RegionDoneCallback::imageEnd()
VRayRenderer:imageEnd()
VRayRenderer::endFrame()
GlobalLightManager::frameEnd()
DirectLightManager::frameEnd()
RayServerInterface::done()
ResourceManager::freeMem()
RayServerInterface::freeMem()
VRayRenderer::clearGeometry()
VRayCameraSampler::frameEnd()
VRayCamera::frameEnd()
VRayRenderer::frameEnd()
RegionDoneCallback::frameEnd()
]
VRayRenderer::endSequence()