c4d.modules.render.VolumeData

class c4d.modules.render.VolumeData

Methods Signatures

VolumeData.GetObjCount(self)	Returns the overall number of objects.
VolumeData.GetSkyCount(self)	Returns the number of skies.
VolumeData.GetCurrentCPU(self)	Returns the current CPU on which the shader is executed.
VolumeData.GetCPUCount(self)	Returns the CPU count the renderer is utilizing.
VolumeData.OutOfMemory(self)	Notify Cinema 4D that a (severe) out-of-memory condition occurred.
VolumeData.SkipRenderProcess(self)	Skips the render process. (Useful for custom renderers.)
VolumeData.ScreenToCamera(self, p)	Transform screen to camera coordinates. During QTVR rendering same point is returned.
VolumeData.CameraToScreen(self, p)	Transform camera to screen coordinates. During QTVR rendering same point is returned.
VolumeData.StatusSetText(self, str)	Set the status bar text during initialization of your shader or videopost effect.
VolumeData.StatusSetBar(self)	Set the progress bar during initialization of your shader or videopost effect.
VolumeData.StatusSetSpinMode(self, on)	Set the render progress bar spinning. Use this to indicate that your plugin is still processing even if the progress bar is not increasing.
VolumeData.GetLightCount(self)	Returns the overall number of lights.
VolumeData.GetLight(self, index)	Get the given light source.
VolumeData.CalcArea(self, light, nodiffuse, ...)	If you code custom illumination models (e.g. different specular function) you can do this for standard lightsources easily.
VolumeData.CalcShadow(self, l, p, bumpn, ...)	Compute a shadow.
VolumeData.IlluminanceAnyPoint(self, p, flags, raybits)	Calculates the light intensity for a given point p.
VolumeData.IlluminateSurfacePoint(self, rl, p, bumpn, ...)	Calculates the intensity of incoming light for a given light and surface point.
VolumeData.CalcVisibleLight(self, ray, maxdist)	Returns the mixed color of all visible lights on a given ray span.
VolumeData.GetRS(self, hitid, p)	Calculates the R/S parameters for a point.
VolumeData.GetWeights(self, hitid, p)	Returns barycentric coordinates for a point on the surface of a polygon.
VolumeData.GetSmoothedNormal(self, hitid, p)	Returns the phong normal for a point.
VolumeData.GetXY(self)	Returns the current X/Y pixel position in render resolution. Render resolution is the screen resolution multiplied by ‘scale’.
VolumeData.SetXY(self, x, y)	Sets the current X/Y pixel position in render resolution. Render resolution is the screen resolution multiplied by ‘scale’.
VolumeData.CalcFgBg(self, foreground, x, y, ...)	Calculates the foreground or background color and alpha at (x, y).
VolumeData.GetLightFalloff(self)	Calculate the light falloff function (light intensity for a distance).
VolumeData.GetRay(self, x, y, ray)	Generate the view ray for a position.
VolumeData.GetVideoPost(self, nth)	Returns the n-th video post effect for this render process.
VolumeData.FindVideoPost(self, id)	Returns a video post effect for this render process by ID.
VolumeData.Init(self, from_)	Initializes this VolumeData object with the data from the from object.
VolumeData.CopyTo(self, dst)	Copy this to another VolumeData.

Inheritance

Parent Class:

• c4d.modules.render.BaseVolumeData

Methods Documentation

VolumeData.GetObjCount(self)

Returns the overall number of objects.

Return type

int

Returns

The total number of objects.

VolumeData.GetSkyCount(self)

Returns the number of skies.

Return type

int

Returns

The number of skies.

VolumeData.GetCurrentCPU(self)

Returns the current CPU on which the shader is executed.

Return type

int

Returns

The running CPU id.

VolumeData.GetCPUCount(self)

Returns the CPU count the renderer is utilizing.

Return type

int

Returns

The number of CPUs.

VolumeData.OutOfMemory(self)

Notify Cinema 4D that a (severe) out-of-memory condition occurred.

Cinema 4D will stop as soon as possible, but there is no guarantee when exactly.

It is possible that your shader could still be called several times, so it has to be programmed to handle this and to be crash-proof.

VolumeData.SkipRenderProcess(self)

Skips the render process. (Useful for custom renderers.)

VolumeData.ScreenToCamera(self, p)

Transform screen to camera coordinates. During QTVR rendering same point is returned.

Parameters

p (c4d.Vector) – The screen coordinate.

Return type

c4d.Vector

Returns

The camera coordinate.

VolumeData.CameraToScreen(self, p)

Transform camera to screen coordinates. During QTVR rendering same point is returned.

Parameters

p (c4d.Vector) – The camera coordinate.

Return type

c4d.Vector

Returns

The screen coordinate.

VolumeData.StatusSetText(self, str)

Set the status bar text during initialization of your shader or videopost effect.

Note

If an empty string is passed the status bar will be cleared.

Parameters

str (str) – The status text to display.

VolumeData.StatusSetBar(self)

Set the progress bar during initialization of your shader or videopost effect.

Note

The value passed will only be displayed if it is bigger than the previous one. To reset the bar call StatusSetText (“”).

VolumeData.StatusSetSpinMode(self, on)

Set the render progress bar spinning. Use this to indicate that your plugin is still processing even if the progress bar is not increasing.

Parameters

on (bool) – True to set the progress bar spinning, False to stop it.

VolumeData.GetLightCount(self)

Returns the overall number of lights.

Return type

int

Returns

The number of lights.

VolumeData.GetLight(self, index)

Get the given light source.

Parameters

index (int) – The index of the light source to return.

Return type

ptr

Returns

The light source.

VolumeData.CalcArea(self, light, nodiffuse, nospecular, specular_exponent, ray_vector, p, bumpn, orign, raybits, ignoreLightColor)

If you code custom illumination models (e.g. different specular function) you can do this for standard lightsources easily.

For area lights you’ll usually want to fall back to the default illumination model though, as otherwise you’d have to rebuild the sample code of area lights!

Parameters

• light (ptr) – The area light to calculate.

• nodiffuse (bool) – True if the diffuse value should not be calculated, otherwise False.

• nospecular (bool) – True if the specular value should not be calculated, otherwise False.

• specular_exponent (float) – Specular exponent to use.

• ray_vector (c4d.Vector) – Ray vector.

• p (c4d.Vector) – The surface point.

• bumpn (c4d.Vector) – The bump normal.

• orign (c4d.Vector) – The original normal.

• raybits (int) –

  The ray bits:

  RAYBIT_NONE	None.
  RAYBIT_REFLECTION	Ray chain contains a reflection ray.
  RAYBIT_TRANSPARENCY	Ray chain contains a transparency ray (refractions are not contained).
  RAYBIT_REFRACTION	Ray chain contains a refraction ray.
  RAYBIT_CUSTOM	Ray chain contains a custom ray.
  RAYBIT_CURR_REFLECTION	Current ray is a reflection ray.
  RAYBIT_CURR_TRANSPARENCY	Current ray is a transparency ray.
  RAYBIT_CURR_REFRACTION	Current ray is a refraction ray.
  RAYBIT_CURR_CUSTOM	Current ray is a custom ray.
  RAYBIT_VOLUMETRICLIGHT	Current ray is used to calculate a volumetric light.
  RAYBIT_ALLOWVLMIX	Custom mixing of visible light sources allowed for the ray; bit must be deleted by shader if used.
  RAYBIT_GI	Current ray is a Global Illumination ray.
  RAYBIT_BLURRY	Current ray is a blurry ray.
  RAYBIT_SSS	Current ray is a subsurface scattering ray.
  RAYBIT_AO	Current ray is an Ambient Occlusion ray.
  RAYBIT_COMPOSITING	Current ray is a compositing ray.

• ignoreLightColor (bool) –

New in version R20: True to ignore the light color into the result, otherwise False.

Return type

Tuple[c4d.Vector, c4d.Vector]

Returns

The diffuse and specular components.

VolumeData.CalcShadow(self, l, p, bumpn, phongn, orign, rayv, transparency, hitid, raybits)

Compute a shadow.

Parameters

• l (ptr) – The illuminating light source.

• p (c4d.Vector) – The point in global coordinates.

• bumpn (c4d.Vector) – The bump normal.

• phongn (c4d.Vector) – The phong normal.

• orign (c4d.Vector) – The original normal.

• rayv (c4d.Vector) – The ray vector.

• transparency (bool) – True if transparencies/alphas for inbetween objects should be evaluated.

• hitid (ptr) – The global RayHitID for the surface intersection (to avoid self shadowing), or RayHitID() if you are not on a surface or do not wish to make use of this avoidance.

• raybits (int) –

  The ray bits:

  RAYBIT_NONE	None.
  RAYBIT_REFLECTION	Ray chain contains a reflection ray.
  RAYBIT_TRANSPARENCY	Ray chain contains a transparency ray (refractions are not contained).
  RAYBIT_REFRACTION	Ray chain contains a refraction ray.
  RAYBIT_CUSTOM	Ray chain contains a custom ray.
  RAYBIT_CURR_REFLECTION	Current ray is a reflection ray.
  RAYBIT_CURR_TRANSPARENCY	Current ray is a transparency ray.
  RAYBIT_CURR_REFRACTION	Current ray is a refraction ray.
  RAYBIT_CURR_CUSTOM	Current ray is a custom ray.
  RAYBIT_VOLUMETRICLIGHT	Current ray is used to calculate a volumetric light.
  RAYBIT_ALLOWVLMIX	Custom mixing of visible light sources allowed for the ray; bit must be deleted by shader if used.
  RAYBIT_GI	Current ray is a Global Illumination ray.
  RAYBIT_BLURRY	Current ray is a blurry ray.
  RAYBIT_SSS	Current ray is a subsurface scattering ray.
  RAYBIT_AO	Current ray is an Ambient Occlusion ray.
  RAYBIT_COMPOSITING	Current ray is a compositing ray.

Return type

c4d.Vector

Returns

The returned shadow value. If there is no shadow, 0.0 will be returned. 1.0 is the maximum shadow value for each component.

VolumeData.IlluminanceAnyPoint(self, p, flags, raybits)

Calculates the light intensity for a given point p.

This routine can calculate the illumination for any point in space and is widely used for transparent volumetric shaders (gases, clouds etc.).

Parameters

• p (c4d.Vector) – The point in global coordinates.

• raybits (int) – The global coordinate point to calculate the illumination for.

• flags (int) –

  The illuminate flags:

  ILLUMINATEFLAGS_NONE	None.
  ILLUMINATEFLAGS_SHADOW	Full shadow calculations.
  ILLUMINATEFLAGS_NOENVIRONMENT	Shadow calculations are enabled but no environment shading will be calculated.
  ILLUMINATEFLAGS_DISABLESHADOWMAP_CORRECTION	Shadow maps evaluate the normal at a surface point, to avoid the problem of self-shadowing (that is otherwise inherent due to the way the algorithm works). If a free point is sampled in space (where no surface is) this correction has to be disabled though, otherwise wrong results will be returned.
  ILLUMINATEFLAGS_DISABLESHADOWCASTERMP_CORRECTION	Private.
  ILLUMINATEFLAGS_LIGHTDIRNORMALS	Private.
  ILLUMINATEFLAGS_NODISTANCEFALLOFF	Do not take distance falloff into account.
  ILLUMINATEFLAGS_NOGRAIN	Do not take grain into account.
  ILLUMINATEFLAGS_BACKLIGHT	Take backlight into account.

• raybits –

  The ray bits:

  RAYBIT_NONE	None.
  RAYBIT_REFLECTION	Ray chain contains a reflection ray.
  RAYBIT_TRANSPARENCY	Ray chain contains a transparency ray (refractions are not contained).
  RAYBIT_REFRACTION	Ray chain contains a refraction ray.
  RAYBIT_CUSTOM	Ray chain contains a custom ray.
  RAYBIT_CURR_REFLECTION	Current ray is a reflection ray.
  RAYBIT_CURR_TRANSPARENCY	Current ray is a transparency ray.
  RAYBIT_CURR_REFRACTION	Current ray is a refraction ray.
  RAYBIT_CURR_CUSTOM	Current ray is a custom ray.
  RAYBIT_VOLUMETRICLIGHT	Current ray is used to calculate a volumetric light.
  RAYBIT_ALLOWVLMIX	Custom mixing of visible light sources allowed for the ray; bit must be deleted by shader if used.
  RAYBIT_GI	Current ray is a Global Illumination ray.
  RAYBIT_BLURRY	Current ray is a blurry ray.
  RAYBIT_SSS	Current ray is a subsurface scattering ray.
  RAYBIT_AO	Current ray is an Ambient Occlusion ray.
  RAYBIT_COMPOSITING	Current ray is a compositing ray.

Return type

c4d.Vector

Returns

The returned color.

Note

The returned color components can exceed values of 1.0!

VolumeData.IlluminateSurfacePoint(self, rl, p, bumpn, phongn, orign, ray_vector, flags, hitid, raybits, cosine_cutoff)

Calculates the intensity of incoming light for a given light and surface point.

Note

Used for custom illumination models.

Parameters

• rl (PyCObject) – The illuminating light.

• p (c4d.Vector) – The surface point.

• bumpn (c4d.Vector) – The bump normal.

• phongn (c4d.Vector) – The phong normal.

• orign (c4d.Vector) – The original normal.

• ray_vector (c4d.Vector) – The ray vector.

• flags (int) –

  The illuminate flags:

  ILLUMINATEFLAGS_NONE	None.
  ILLUMINATEFLAGS_SHADOW	Full shadow calculations.
  ILLUMINATEFLAGS_NOENVIRONMENT	Shadow calculations are enabled but no environment shading will be calculated.
  ILLUMINATEFLAGS_DISABLESHADOWMAP_CORRECTION	Shadow maps evaluate the normal at a surface point, to avoid the problem of self-shadowing (that is otherwise inherent due to the way the algorithm works). If a free point is sampled in space (where no surface is) this correction has to be disabled though, otherwise wrong results will be returned.
  ILLUMINATEFLAGS_DISABLESHADOWCASTERMP_CORRECTION	Private.
  ILLUMINATEFLAGS_LIGHTDIRNORMALS	Private.
  ILLUMINATEFLAGS_NODISTANCEFALLOFF	Do not take distance falloff into account.
  ILLUMINATEFLAGS_NOGRAIN	Do not take grain into account.
  ILLUMINATEFLAGS_BACKLIGHT	Take backlight into account.

• hitid (PyCObject) – The global RayHitID.

• raybits (int) –

  The ray bits:

  RAYBIT_NONE	None.
  RAYBIT_REFLECTION	Ray chain contains a reflection ray.
  RAYBIT_TRANSPARENCY	Ray chain contains a transparency ray (refractions are not contained).
  RAYBIT_REFRACTION	Ray chain contains a refraction ray.
  RAYBIT_CUSTOM	Ray chain contains a custom ray.
  RAYBIT_CURR_REFLECTION	Current ray is a reflection ray.
  RAYBIT_CURR_TRANSPARENCY	Current ray is a transparency ray.
  RAYBIT_CURR_REFRACTION	Current ray is a refraction ray.
  RAYBIT_CURR_CUSTOM	Current ray is a custom ray.
  RAYBIT_VOLUMETRICLIGHT	Current ray is used to calculate a volumetric light.
  RAYBIT_ALLOWVLMIX	Custom mixing of visible light sources allowed for the ray; bit must be deleted by shader if used.
  RAYBIT_GI	Current ray is a Global Illumination ray.
  RAYBIT_BLURRY	Current ray is a blurry ray.
  RAYBIT_SSS	Current ray is a subsurface scattering ray.
  RAYBIT_AO	Current ray is an Ambient Occlusion ray.
  RAYBIT_COMPOSITING	Current ray is a compositing ray.

• cosine_cutoff (bool) – True if cosine cut-off should be used, otherwise False.

Return type

Tuple[c4d.Vector, c4d.Vector]

Returns

A tuple with the color result for the calculation and the light to point vector.

VolumeData.CalcVisibleLight(self, ray, maxdist)

Returns the mixed color of all visible lights on a given ray span.

Parameters

• ray (c4d.Vector) – The ray span.

• maxdist (float) – The maximum distance for the lights.

Return type

Tuple[c4d.Vector, c4d.Vector]

Returns

The mixed color of the lights and a value indicating if some light sources have a dust effect (!= 0 in this case).

VolumeData.GetRS(self, hitid, p)

Calculates the R/S parameters for a point.

If you want to calculate weighted data (e.g. based upon a color for each polygon point) you can do this the following way:

r, s = GetRS(hitid, p)
result = [color a] * (1.0-r-s) + [color d]*r + [color c]*s

Parameters

• hitid (ptr) – The global RayHitID.

• p (c4d.Vector) – The point.

Return type

Tuple[bool, float, float]

Returns

If the polygon is a quadrangle then the first value holds True for the second part (a-c-d) of the quadrangle or False for the first part (a-b-c). If the polygon is a triangle then this is the same as the first part of a quadrangle (a-b-c).

The 2nd and 3rd values are the R and S parameters for point p.

VolumeData.GetWeights(self, hitid, p)

Returns barycentric coordinates for a point on the surface of a polygon.

Cinema 4D uses enhanced interpolation routines for quadrangles, so you’ll get a higher quality using it instead of considering a quadrangle as two triangles.

The routine works for any type of polygon, including triangles and non-coplanar quadrangles.

Note

The function returns a tuple with the weight factors for the global polygon with ID hitid at p.

Works similar to GetRS(), but has a higher quality.

Parameters

• hitid (ptr) – The global RayHitID.

• p (c4d.Vector) – Point on polygon.

Return type

Tuple[float, float, float, float]

Returns

A tuple with the respective weight factors for points A, B, C and D.

VolumeData.GetSmoothedNormal(self, hitid, p)

Returns the phong normal for a point.

Parameters

• hitid (ptr) –

  The global RayHitID.

  Note

  Must be a valid RayHitID.

• p (c4d.Vector) –

  The point for the phong normal.

  Note

  The point must be within the surface boundaries of the polygon.

Return type

c4d.Vector

Returns

The phong normal.

VolumeData.GetXY(self)

Returns the current X/Y pixel position in render resolution. Render resolution is the screen resolution multiplied by ‘scale’.

Return type

Tuple[int, int, int]

Returns

The X, Y pixel positions and render scale.

Note

X/scale and Y/scale is the screen position.

VolumeData.SetXY(self, x, y)

Sets the current X/Y pixel position in render resolution. Render resolution is the screen resolution multiplied by ‘scale’.

Note

X/scale and Y/scale is the screen position.

Note

Some Shaders use the screen pixel position. Plugins (like the Baker for instance) can change this position without having to render an image.

Parameters

• x (float) – The X pixel position to set.

• y (float) – The Y pixel position to set.

VolumeData.CalcFgBg(self, foreground, x, y, subx, suby)

Calculates the foreground or background color and alpha at (x, y).

Parameters

• foreground (bool) – True to calculate the foreground color. Otherwise the background color is calculated.

• x (int) – X coordinate.

• y (int) – Y coordinate.

• subx (int) – Sub pixel X position. (0 <= subx <= 15)

• suby (int) – Sub pixel Y position. (0 <= suby <= 15)

Return type

Tuple[ c4d.Vector, float]

Returns

The background/foreground color and alpha.

VolumeData.GetLightFalloff(self)

Calculate the light falloff function (light intensity for a distance).

VolumeData.GetRay(self, x, y, ray)

Generate the view ray for a position.

Note

This function does not set Ray.pp [0..2], Ray.vv [0..2], Ray.transport and Ray.ior.

Parameters

• x (float) – The X position for the view ray in screen space coordinates.

• y (float) – The Y position for the view ray in screen space coordinates.

• ray (c4d.modules.render.Ray) – The view ray.

VolumeData.GetVideoPost(self, nth)

Returns the n-th video post effect for this render process.

Parameters

nth (int) – nth The nth index of the videopost effect.

Return type

Optional[c4d.BaseList2D]

Returns

The video post, or None if the index is too large.

VolumeData.FindVideoPost(self, id)

Returns a video post effect for this render process by ID.

Parameters

id (int) – The video post effect ID.

Return type

Optional[c4d.BaseList2D]

Returns

The found video post, or None if it doesn’t exist.

VolumeData.Init(self, from_)

Initializes this VolumeData object with the data from the from object.

Note

Only the most essential parts are copied over, including the render instance.

Parameters

from (c4d.modules.render.VolumeData) – Source object.

VolumeData.CopyTo(self, dst)

Copy this to another VolumeData.

Parameters

dst (c4d.modules.render.VolumeData) – The destination VolumeData.