VRay::RenderElement Class Reference

Helper class that wraps a plugin instance enabling a certain render element. More...

#include <vraysdk.hpp>

Classes
struct	GetDataOptions
	Controls what the buffer returned by getData() contains. More...
struct	Info
	This structure is used to return information about a particular channel in the VFB. More...

Public Types
enum	BinaryFormat {   BF_FLOAT = 1 , BF_3FLOAT , BF_2FLOAT , BF_INT ,   BF_3FLOAT_SIGNED , BF_4FLOAT }
	Render channel binary format / storage data type. More...
enum	PixelFormat {   PF_DEFAULT = -1 , PF_BW_BIT8 = 100 , PF_BW_BIT16 , PF_BW_BIT32 ,   PF_BW_HALF , PF_BW_FLOAT , PF_RGB_BIT8 = 200 , PF_RGB_BIT16 ,   PF_RGB_HALF , PF_RGB_FLOAT , PF_RGBA_BIT8 = 300 , PF_RGBA_BIT16 ,   PF_RGBA_HALF , PF_RGBA_FLOAT }
	This describes the desired data format for getData(). More...
enum	Type {   NONE = -1 , ATMOSPHERE = 100 , DIFFUSE , REFLECT ,   REFRACT , SELFILLUM , SHADOW , SPECULAR ,   LIGHTING , GI , CAUSTICS , RAWGI ,   RAWLIGHT , RAWSHADOW , VELOCITY , RENDERID ,   MTLID , NODEID , ZDEPTH , REFLECTION_FILTER ,   RAW_REFLECTION , REFRACTION_FILTER , RAW_REFRACTION , REALCOLOR ,   NORMALS , BACKGROUND , ALPHA , COLOR ,   WIRECOLOR , MATTESHADOW , TOTALLIGHT , RAWTOTALLIGHT ,   BUMPNORMALS , SAMPLERATE , SSS , DRBUCKET ,   VRMTL_REFLECTGLOSS , VRMTL_REFLECTHIGLOSS , VRMTL_REFRACTGLOSS , SHADEMAP_EXPORT ,   REFLECT_ALPHA , VRMTL_REFLECTIOR , MTLRENDERID , NOISE_LEVEL ,   WORLD_POSITION , DENOISED , WORLD_BUMPNORMAL , DEFOCUS_AMOUNT ,   EFFECTS_RESULT = 153 , TOON , RENDERTIME = 157 , CRYPTOMATTE ,   LIGHTING_ANALYSIS = 160 , LIGHT_SELECT = 163 , VRMTL_METALNESS = 165 , TOON_LIGHTING = 180 ,   TOON_SPECULAR = 181 , VRMTL_SHEEN_COLOR = 183 , RAW_SHEEN_REFLECTION = 184 , SHEEN_FILTER = 185 ,   VRMTL_SHEEN_GLOSSINESS = 186 , SHEEN_REFL_ALPHA = 187 , COAT_REFL_ALPHA = 188 , VRMTL_COAT_COLOR = 189 ,   RAW_COAT_REFLECTION = 190 , COAT_FILTER = 191 , VRMTL_COAT_GLOSSINESS = 192 , LAST ,   USER =1000 , COVERAGE = USER + 5001 , MATERIAL_SELECT = USER + 5003 , MULTIMATTE = USER + 5004 ,   MULTIMATTE_ID = USER + 5005 , OBJECT_SELECT = USER + 5006 , EXTRA_TEX = USER + 5007 , EXTRA_TEX_INT = USER + 5008 ,   EXTRA_TEX_FLOAT = USER + 5009 }
	The render channal types/aliases are used to identify some common channels. More...

Public Member Functions
	RenderElement ()
	Default construct an invalid object.
BinaryFormat	getBinaryFormat () const
	Get the binary format of pixels in this render element.
size_t	getData (void **data, const GetDataOptions &options) const
size_t	getDataIntoBuffer (const GetDataOptions &options, void *data) const
PixelFormat	getDefaultPixelFormat () const
	Get the default format used by the getData method for this render element.
VRayImage *	getImage (const GetImageOptions &options, int layerIndex=0) const
VRayImage *	getImage (const ImageRegion *rgn=NULL, int layerIndex=0) const
std::string	getMetadata () const
	Get render element metadata. Currently works only for Cryptomatte render element and returns manifest and metadata.
std::string	getName () const
	Get the display name of this render element.
Plugin	getPlugin () const
	Get the plugin instance in the scene that enables this render element. Might be invalid for special channels like EffectsResult.
Type	getType () const
	Get the type of the render element.
	operator bool () const

Static Public Member Functions
static void	releaseData (void *data)
	Call this to release data allocated by the getData method.

Friends
class	RenderElements

Detailed Description

Helper class that wraps a plugin instance enabling a certain render element.

Member Enumeration Documentation

BinaryFormat

enum VRay::RenderElement::BinaryFormat

Render channel binary format / storage data type.

Enumerator
BF_FLOAT	A single float number (e.g. z-depth).
BF_3FLOAT	3 float numbers (e.g. RGB color).
BF_2FLOAT	2 signed float numbers (e.g. uv coordinates or pixel screen velocity).
BF_INT	A single integer number (e.g. render ID, material ID etc).
BF_3FLOAT_SIGNED	3 signed float numbers (e.g. surface normals).
BF_4FLOAT	4 float numbers (e.g. RGBA color).

PixelFormat

enum VRay::RenderElement::PixelFormat

This describes the desired data format for getData().

Enumerator
PF_BW_BIT8	1-byte greyscale/integer.
PF_BW_BIT16	2-byte greyscale/integer.
PF_BW_BIT32	4-byte greyscale/integer.
PF_BW_HALF	2-byte half-float greyscale (currently not supported).
PF_BW_FLOAT	4-byte float greyscale.
PF_RGB_BIT8	3x1 bytes RGB.
PF_RGB_BIT16	3x2 bytes RGB.
PF_RGB_HALF	3x2 bytes half-float RGB (currently not supported).
PF_RGB_FLOAT	3x4 bytes float RGB.
PF_RGBA_BIT8	4x1 bytes RGBA.
PF_RGBA_BIT16	4x2 bytes RGBA.
PF_RGBA_HALF	4x2 bytes half-float RGBA (currently not supported).
PF_RGBA_FLOAT	4x4 bytes float RGBA.

Type

enum VRay::RenderElement::Type

The render channal types/aliases are used to identify some common channels.

Enumerator
NONE	Unspecified channel.
ATMOSPHERE	Atmospheric effects channel.
DIFFUSE	Diffuse filter VFB channel. This channel is generated by V-Ray.
REFLECT	Reflection VFB channel. This channel must be generated by shaders.
REFRACT	Refraction VFB channel. This channel must be generated by shaders.
SELFILLUM	Self-illumination VFB channel. This channel must be generated by shaders.
SHADOW	Shadow VFB channel. This channel is generated by V-Ray.
SPECULAR	Specular VFB channel. This channel is generated by V-Ray.
LIGHTING	Lighting VFB channel. This channel is generated by V-Ray.
GI	GI VFB channel. This channel is generated by V-Ray.
CAUSTICS	Caustics VFB channel. This channel is generated by V-Ray.
RAWGI	Raw GI VFB channel. This channel is generated by V-Ray.
RAWLIGHT	Raw light VFB channel. This channel is generated by V-Ray.
RAWSHADOW	Raw shadow VFB channel. This channel is generated by V-Ray.
VELOCITY	Velocity VFB channel. This channel is generated by V-Ray.
RENDERID	Render ID VFB channel. This channel is generated by V-Ray.
MTLID	Mtl ID VFB channel. This channel is generated by V-Ray.
NODEID	Node ID VFB channel. This channel is generated by V-Ray.
ZDEPTH	Z-Depth VFB channel. This channel is generated by V-Ray.
REFLECTION_FILTER	Reflection filter VFB channel. This channel must be generated by shaders.
RAW_REFLECTION	Raw reflection VFB channel. This channel must be generated by shaders.
REFRACTION_FILTER	Refraction filter VFB channel. This channel must be generated by shaders.
RAW_REFRACTION	Raw refraction VFB channel. This channel must be generated by shaders.
REALCOLOR	Real color VFB channel.
NORMALS	Normals VFB channel. This channel is generated by V-Ray.
BACKGROUND	Background VFB channel. This channel is generated by V-Ray.
ALPHA	Alpha VFB channel. This is always created by V-Ray and there can't be multiple instances. It's easier to use getImage() for Alpha.
COLOR	RGB VFB channel. This is always created by V-Ray and there can't be multiple instances. It's easier to use getImage() for RGB.
WIRECOLOR	Wire color channel where each object appears with a solid color. This channel is generated by V-Ray.
MATTESHADOW	Matte shadow channel where full shadows are white and areas not in shadow are black; essentially this is (rawShadow)/(rawLight+rawShadow). This channel is generated by V-Ray.
TOTALLIGHT	The total diffuse lighting (direct+indirect) falling on a surface. This channel is generated by V-Ray.
RAWTOTALLIGHT	The raw total diffuse lighting (direct+indirect) falling on a surface. This channel is generated by V-Ray.
BUMPNORMALS	The normals modified with bump map. This channel must be generated by shaders.
SAMPLERATE	The sample rate for the image samplers.
SSS	A channel used for VRayFastSSS2 material sub-surface portion.
DRBUCKET	A channel that keeps track of which DR server rendered a particular bucket (it is a Color buffer that stores server name strings prerendered, as text, white on black)
VRMTL_REFLECTGLOSS	A VRayMtl reflection glossiness VFB channel. This channel is generated by V-Ray.
VRMTL_REFLECTHIGLOSS	A VRayMtl reflection hilight glossiness VFB channel. This channel is generated by V-Ray.
VRMTL_REFRACTGLOSS	A VRayMtl reflection glossiness VFB channel. This channel is generated by V-Ray.
SHADEMAP_EXPORT	A channel that keeps the fragment coordinates in camera space.
REFLECT_ALPHA	Used by matte materials to store the alpha of the reflections.
VRMTL_REFLECTIOR	A VRayMtl reflection IOR VFB channel. This channel is generated by V-Ray.
MTLRENDERID	Mtl render ID VFB channel. This channel is generated by V-Ray.
NOISE_LEVEL	The noise level as estimated by the Adaptive and Progressive image samplers. Used for denoising purposes.
WORLD_POSITION	The position in world space. Used for denoising purposes.
DENOISED	A denoised version of the image. Adding this render element enables denoising.
WORLD_BUMPNORMAL	Normal with bump mapping in world space.
DEFOCUS_AMOUNT	Pixel blur, combination of DOF and moblur. Used for denoising purposes.
EFFECTS_RESULT	Channel for all post effects.
TOON	Toon effect channel.
RENDERTIME	Per-pixel render time.
CRYPTOMATTE	Used for Cryptomatte render channel output.
LIGHTING_ANALYSIS	The lighting analysis overlay.
LIGHT_SELECT	Link this in the channels parameters of your lights.
VRMTL_METALNESS	VRayMtl metalness parameter.
TOON_LIGHTING	Direct toon diffuse lighting.
TOON_SPECULAR	Direct toon specular lighting.
VRMTL_SHEEN_COLOR	VRayMtl sheen color parameter (sheen filter uninfluenced by Fresnel weight, reflection and refraction color).
RAW_SHEEN_REFLECTION	Raw sheen indirect reflection VFB channel.
SHEEN_FILTER	Sheen filter VFB channel.
VRMTL_SHEEN_GLOSSINESS	VRayMtl sheen glossiness parameter.
SHEEN_REFL_ALPHA	Used by matte materials to store the alpha of the sheen reflections.
COAT_REFL_ALPHA	Used by matte materials to store the alpha of the coat reflections.
VRMTL_COAT_COLOR	VRayMtl coat highlight color (coat filter uninfluenced by Fresnel weight, reflection and refraction color).
RAW_COAT_REFLECTION	Raw coat indirect reflection VFB channel.
COAT_FILTER	Coat filter VFB channel.
VRMTL_COAT_GLOSSINESS	VRayMtl coat glossiness parameter.
LAST	not a type, just a delimiter
USER	User defined channel indices start from here.
COVERAGE	Pixel coverage.
MATERIAL_SELECT	Material select.
MULTIMATTE	RGB matte for up to 3 objects.
MULTIMATTE_ID	RGB matte using material IDs.
OBJECT_SELECT	Selects by object/material ID.
EXTRA_TEX	A single texture override is applied to the whole scene (e.g. Dirt)
EXTRA_TEX_INT	A single texture override is applied to the whole scene (e.g. Dirt)
EXTRA_TEX_FLOAT	A single texture override is applied to the whole scene (e.g. Dirt)

Member Function Documentation

getData()

size_t VRay::RenderElement::getData	(	void **	data,
		const GetDataOptions &	options
	)		const

Retrieves the render element raw data. The returned memory buffer must be freed with releaseData(data)! WARNING: If Nvidia AI upscaling is enabled, then the returned image/data will have even dimentions.

Parameters

[out]

data

a pointer to a void pointer which will receive the address of the raw data buffer. Free it with releaseData() when done.

Returns

the length in bytes of the returned memory buffer.

Remarks

the returned memory buffer must be freed with releaseData(data).

getDataIntoBuffer()

size_t VRay::RenderElement::getDataIntoBuffer	(	const GetDataOptions &	options,
		void *	data
	)		const

Retrieves the render element raw data into the buffer. WARNING: If Nvidia AI upscaling is enabled, then the returned image/data will have even dimentions.

Parameters

options	Image options (crop, color correct, etc.).
buf	The output data buffer. If nullptr - returns required buffer size.

Returns

If data is nullptr returns required buffer size; 0 on error; 1 on success.

getImage() [1/2]

VRayImage * VRay::RenderElement::getImage	(	const GetImageOptions &	options,
		int	layerIndex = 0
	)		const

Allocate a new copy of the channel data as a VRayImage instance WARNING: If Nvidia AI upscaling is enabled, then the returned image/data will have even dimentions.

Parameters

options	Use to modify behavior compared to getImage(void) - crop, color correct, etc.
layerIndex	For multi-layer elements only. The Cryptomatte layer index (between 0 and num_level/2). For ObjectSelect value 1=filter layer and 2=alpha layer.

Returns

NULL on failure (e.g. invalid layerIndex)

getImage() [2/2]

VRayImage * VRay::RenderElement::getImage	(	const ImageRegion *	rgn = NULL,
		int	layerIndex = 0
	)		const

Allocate a new copy of the channel data as a VRayImage instance WARNING: If Nvidia AI upscaling is enabled, then the returned image/data will have even dimentions.

Parameters

rgn	an optional image region rectange; NULL means the whole image.
layerIndex	For multi-layer elements only. The Cryptomatte layer index (between 0 and num_level/2). For ObjectSelect value 1=filter layer and 2=alpha layer.

Returns

NULL on failure (e.g. invalid layerIndex)

operator bool()

VRay::RenderElement::operator bool ( ) const

inline

Check if there is a valid plugin representing this render element in the scene. If false, creation failed. Exception: COLOR, ALPHA and EFFECTS_RESULT will return false as they are implicit (without a corresponding instance), but they can still be used with getImage/getData. EFFECTS_RESULT may fail getImage/getData if there are no post effects.

---

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

• /home/jenkins/ci/cgrepo/appsdk/VRay_SDK_CPP/include/vraysdk.hpp