Cmaxwell

The Cmaxwell class describes the whole Maxwell Render scene.

Friend classes

CoptionsReadMXS, CsceneInfo, CmultiValue, Cmaterial, CmaterialLayer, CmaterialEmitter, Creflectance, Ccoating, Cbsdf, Ccamera, Cobject and CmaxwellMxi.

Sub-classes

CoptionsReadMXS, CsceneInfo, CmultiValue, Cmaterial, CmaterialLayer, CmaterialEmitter, Creflectance, Ccoating, Cbsdf, Ccamera and Cobject.

Properties

Enumerations

typeCallback and InteractiveFlags.

Methods

Static Methods

Cmaxwell

Class constructor. To create a Cmaxwell pointer it is needed to define a callback (function pointer). This callback returns errors/warnings/info during the read/write processes.

Examples

byte callback( byte isError, const char *pMethod, const char *pError, const void *pValue )
{
  if ( isError )
  {
    printf( err, "Error in Method = %s \n error = %s \n value = %d\n", pMethod, pError, pValue );
  }
  return ( 0 );
}
 
Cmaxwell* pMaxwell = new Cmaxwell( callback );

# PyMaxwell includes a predefined callback function for Cmaxwell constructor called "mwcallback"
 
 pMaxwell = Cmaxwell( mwcallback );

getMxsVersion

Gets MXS file version.

getMostRecentVersionMXS

Gets most recent MXS version supported.

getPluginID

Gets the plug-in identifier from which the MXS was created (string stored in the scene file to know which exporter has generated the MXS file).

setPluginID

Gets the plug-in identifier from which the MXS was created (string stored in the scene file to know which exporter has generated the MXS file).

isProtectionEnabled

Gets scene protection state in Maxwell Studio (ability to export to other formats). Protection is enabled by default.

enableProtection

Sets scene protection state in Maxwell Studio (ability to export to other formats). Protection is enabled by default.

freeGeometry

Deletes all geometry of the scene.

freeScene

Resets the scene. Cleans all objects, geometry, materials, etc.

getScenePreview

Preview image of the scene stored in the file (useful for thumbnals).

Parameters

Return value

C++

Crgb8 pointer to the preview image. The memory pointed belongs to the scene, so the programmer must not free it.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3).

setScenePreview

Sets the scene preview image.

Parameters

Return value

0 = Error setting scene preview image.

1 = Success.

readPreview

Sets the scene preview from another MXS.

Parameters

Return value

C++

Crgb8 pointer to the preview image. The memory pointed belongs to the scene, so the programmer must not free it.

Python

NumPy array containing the RGB image. Array dimensions: (height, width, 3).

setInputDataType

Sets the axis orientation of the scene.

Parameters

setSinglePrecisionOfGeometry

Uses floats instead of doubles for geometry.

addCluster

Creates a triangle cluster in the scene.

Parameters

Return value

Returns a Cmaxwell::Ccluster object, that is a reference to the cluster added to the scene.

Examples

Cmaxwell::Ccluster cluster = scene->addCluster( "cluster1" );

cluster = scene.addCluster( "cluster1" );

getObject

Gets a object reference from the scene.

Return value

Returns the Cobject with the given name or a null object if there is not an object with that name ( Cmaxwell::Cobject::isNull() == true ).

createMesh

Creates a mesh with the given parameters and adds it to the scene. If nVertes, nNormals and nTriangles are equal to 0, a NULL object is created.

Parameters

Return value

Cmaxwell::Cobject reference to the new mesh object created in the scene. Null object if it was not created (Cmaxwell::Cobject::isNull() = true).

createInstancement

Creates an instance of the Cobject "object" (must be a mesh). If the object name exist, it will add a number at the end, in example: two instancements are created with the name "myname", the second one will be named "myname1". Creating huge amounts of instancements using the same name will be too slow because the name assignation algorithm will try alternative names this way:

1. Creating instancement "instance": OK.
2. Creating instancement "instance": Name exist. Trying "instance1": OK.
3. Creating instancement "instance": Name exist. Trying "instance1": Name exists. Trying "instance2": OK.

And so on...

So it's highly reccommended to assign unique names in each instancement creation when we create a lot of them. A good example of creating instancements is provided here.

Parameters

Return value

Cmaxwell::Cobject reference to the new instance object created in the scene. Null object if it was not created (Cmaxwell::Cobject::isNull() = true).

createProxy

Creates a proxy object that points to the given MXS path.

Return value

Cmaxwell::Cobject reference to the new proxy object created in the scene. Null object if it was not created (Cmaxwell::Cobject::isNull() = true).

createRFRK

Method used to create RealFlow objects. Returns a null object that can be filled with Cmaxwell::Cobject::setRfrkParameters().

Cmaxwell::Cobject reference to the new RFRK object created in the scene. Null object if it was not created (Cmaxwell::Cobject::isNull() = true).

addObject

Adds an existent object into the scene. It is useful for instance for importing objects from one scene to other.

Return value

Cmaxwell::Cobject reference to the object added in the scene. Null object if it was not created (Cmaxwell::Cobject::isNull() = true).

mergeMeshes

Merges an array of meshes into a single mesh. The original meshes are not removed (it can be done later calling Cmaxwell::Cobject::free() ).

Return value

Cmaxwell::Cobject reference to the new merged object created in the scene. Null object if it was not created (Cmaxwell::Cobject::isNull() = true).

Examples

list = []
list.append(scene.getObject('sphere'));
list.append(scene.getObject('cube'));
newobject = scene.mergeMeshes('merged',list);    

addCamera

Adds a new camera to the scene with the given parameters.

Parameters

Return value

Returns a Cmaxwell::Ccamera object, that is a reference to the camera added to the scene. Null if it was not created (Cmaxwell::Ccamera::isNull() = true).

Examples

Cmaxwell* scene = new Cmaxwell(mwcallback);
Cmaxwell::Ccamera camera = scene->addCamera( "Camera1", 1, 0.1, 0.1, 0.1, 500, "CIRCULAR", 90.0, 0, 25, 800, 600, 1, 0 );

scene = Cmaxwell(mwcallback);
scene.readMXS('c:/scenes/myscene.mxs');
camera = scene.addCamera(  "Camera1", 1, 0.1, 0.1, 0.1, 500, "CIRCULAR", 90.0, 0, 25, 800, 600, 1, 0 );

getCamera

Gets a camera requested by name.

Return value

Returns a Cmaxwell::Ccamera object, that is a reference to the camera added to the scene. Null if it was not created (Cmaxwell::Ccamera::isNull() = true).

getActiveCamera

Gets the active camera of the scene.

Return value

Returns a Cmaxwell::Ccamera object, that is a reference to the camera added to the scene. Null if it was not created (Cmaxwell::Ccamera::isNull() = true).

setPath

Sets the path and depth for the given channel.

Parameters

Return values

0 = Error setting path.

1 = Success.

getPath

Gets path of the given channel.

Parameters

Return value

C++

Output path of the channel.

Python

(path,outputBitDepthMode) = Tuple containing the output path of the channel and its bit depth.

addSearchingPath

Adds a path to look for missing textures, ior and ies files.

Return value

0 = Error adding searching path.

1 = Success.

getSearchingPaths

Returns an array of strings (lenght and content) with all searching paths of the scene (textures, ior files, hdr files, ies etc).

Parameters

Return value

C++

0 = Error getting searching paths.

1 = Success

Python

List of paths

getSunPositionType

Gets sun positon type.

Parameters

Return value

C++

0 = Error getting sun position type.

1 = Success.

Python

Sun position type.

setSunPositionType

Sets sun position type.

Parameters

Return value

0 = Error setting sun position type.

1 = Success.

getSkyConstant

Gets the parameters of the constant (non physical) sky.

Parameters

Return value

C++

0 = Error getting constant sky parameters.

1 = Success.

Python

Tuple containing all constant sky parameters.

setSkyConstant

Sets the parameters of the constant (non physical) sky.

Parameters

Return value

0 = Error setting constant sky parameters.

1 = Success.

getSunLongitudeAndLatitude

Gets the location of the sun when Cmaxwell::getSunPositionType() = 0.

Parameters

Return value

C++

0 = Error getting sun longitude and latitude.

1 = Success.

Python

Tuple contaning all sun longitude and latittude values.

setSunLongitudeAndLatitude

Sets the location of the sun when Cmaxwell::getSunPositionType() = 0.

Parameters

Return values

0 = Error setting sun longitude and latitude.

1 = Success.

getSunAngles

It is an alternative way to get/set the sun position based on spheric angles.

Parameters

Return values

C++

0 = Error getting sun angles.

1 = Success

Python

Tuple containing zenith and azimuth angles.

Examples

byte ok;
real zenith;
real azimuth;
ok = scene->getSunAngles( zenith, azimuth );

zenith,azimuth = scene.getSunAngles();

setSunAngles

It is an alternative way to get/set the sun position based on spheric angles.

Parameters

Return values

0 = Error setting sun angles.

1 = Success.

getSunDirection

Gets sun direction vector. It is an alternative way to set the sun position based on a direction.

Return value

C++

0 = Error getting sun direction.

1 = Success.

Python

Sun direction vector

setSunDirection

Sets sun direction vector. It is an alternative way to set the sun position based on a direction.

Return value

0 = Error setting sun direction.

1 = Success.

getSunRotation

Gets the ground rotation of the sky hemisphere.

Parameters

Return value

C++

0 = Error getting sun rotation.

1 = Success.

Python

Ground rotation.

setSunRotation

Sets the ground rotation of the sky hemisphere.

Parameters

Return value

0 = Error setting sun rotation.

1 = Success.

getSunProperties

Gets the sun properties used for both physical and constant skies when sun is enabled.

Parameters

Return values

C++

0 = Error getting sun properties.

1 = Success.

Python

Tuple containing the sun properties.

setSunProperties

Sets the sun properties used for both physical and constant skies when sun is enabled.

Parameters

Return values

0 = Error setting sun properties.

1 = Success.

getPhysicalSkyAtmosphere

Gets the atmosphere parameters of the physical sky.

Parameters

Return values

C++

0 = Error getting atmosphere parameters.

1 = Success.

Python

Tuple containing all atmosphere parameters.

setPhysicalSkyAtmosphere

Sets the atmosphere parameters of the physical sky.

Parameters

Return values

0 = Error setting atmosphere parameters.

1 = Success.

getActiveSky

Gets the active sky used.

Return value

Active sky name. "constant " = constant sky, "physical" = physical sky, NULL = no sky.

setActiveSky

Sets the active sky.

Parameters

Return values

0 = Error setting active sky.

1 = Success.

getSunDirectionUsedForRendering

Returns the sun direction. If the sun position was set through a direction vector, it returns the same vector. If the sun position was set through latitude/longitude or through angles it returns the translation to a direction. This function is mainly used for drawing the sky in a viewport.

Return value

C++

0 = Error getting sun direction.

1 = Success

Python

Sun direction vector.

saveSkyToHDR

Saves current sky to an HDR file in the given path with the given resolution.

Return value

0 = Error saving HDR.

1 = Success.

saveSkyToPreset

Saves current physical sky values to a sky preset file.

Return value

0 = Error saving sky.

1 = Success.

loadSkyFromPreset

Loads a preset file into the scene replacing current physical sky values.

Return value

0 = Error loading sky.

1 = Success.

getSkyColor

Returns sky RGB color (already tonemapped and after exposure is applied) of the current sky values in the given direction.

Return value

C++

0 = Error getting sky color.

1 = Success.

Python

Tuple containing 'hdr' and 'ldr' colors.

getSkyColorNoTonemapped

Returns sky RGB color (without tonemapping nor exposure) of the current sky values in the given direction.

Return value

C++

0 = Error getting sky color.

1 = Success.

Python

Cvector containing the HDR color.

isEnvironmentEnabled

Gets IBL (Image Based Lighting) state.

Return value

C++

0 = Error getting IBL state.

1 = Success.

Python

IBL state.

enableEnvironment

Sets the IBL (Image Based Lighting) on/off.

Return value

0 = Error getting IBL state.

1 = Success.

setEnvironmentWeight

Sets the value for the global multiplier of all the environment layers.

Return value

0 = Error setting environment weight.

1 = Success.

getEnvironmentWeight

Sets the value for the global multiplier of all the environment layers.

Return value

C++

0 = Error getting IBL state.

1 = Success.

Python

Environment weight.

getEnvironmentLayer

Gets the parameters of each environment layer.

Parameters

Return value

C++

0 = Error getting environment layer values.

1 = Success.

Python

Tuple containing all environment layer values.

setEnvironmentLayer

Sets the parameters of each environment layer.

Parameters

Return value

0 = Error setting environment layer values.

1 = Success.

readMaterial

Reads a material from disk.

Return value

Returns a Cmaxwell::Cmaterial object. Null if it was not created (Cmaxwell::Cmaterial::isNull() = true).

createMaterial

Creates a material with the given name and adds it to the scene if the parameter addToScene is true (default).

Return value

Returns a Cmaxwell::Cmaterial object. Null if it was not created (Cmaxwell::Cmaterial::isNull() = true).

getMaterial

Given the name of a material, returns its Cmaxwell::Cmaterial reference.

Return value

Returns a Cmaxwell::Cmaterial object. Null if it was not created (Cmaxwell::Cmaterial::isNull() = true).

addMaterial

Adds a material to the scene and returns a reference to the added material.

Return value

Returns a Cmaxwell::Cmaterial object. Null if it was not created (Cmaxwell::Cmaterial::isNull() = true).

eraseUnusedMaterials

Removes unused materials from the scene.

Return value

0 = Error erasing unused materials.

1 = Success.

setOverrideMaterial

Sets the path and state (enabled/disabled) the material that overrides all the materials of the scene (except emitter materials).

Parameters

getOverrideMaterial

Gets the path and state (enabled/disabled) of the material that overrides all the materials of the scene (except emitter materials).

Return value

Requesting override material: File name of the MXM.

Requesting override material state: true if override material is enabled, false if not.

setDefaultMaterial

Sets the path and state (enabled/disabled) the material that will be used for all the objects/triangles without material.

Parameters

getDefaultMaterial

Gets the path and state (enabled/disabled) of the material that will be used for all the objects/triangles without material.

Return value

Requesting default material: File name of the MXM.

Requesting default material state: true if default material is enabled, false if not.

getRenderParameter, setRenderParameter

Gets/sets the value of the render parameter given by name.

Parameters

Return value

C++

0 = Error getting/setting render parameter.

1 = Success.

Python

• Setting parameter:

0 = Error setting render parameter.

1 = Success.

• Getting parameter:

Parameter value.

getToneMapping

Gets the tonemapping values.

Return value

C++

0 = Error getting tonemapping value.

1 = Success.

Python

Tuple containing 'monitorGamma' and 'burn' values.

setToneMapping

Sets the tonemapping values.

Return value

0 = Error setting tonemapping value.

1 = Success.

getActiveToneMapping

Gets the active tonemapping used: "BASIC" or "ADVANCED", default "BASIC" (Extensions only use "BASIC").

readMXS

Read scene from disk.

Parameters

Return values

0 = Error reading scene.

1 = Success.

writeMXS

Write the scene to disk.

Return value

0 = Error writing scene to disk.

1 = Success.

setDiffraction

Sets diffraction parameters.

Parameters

Return value

0 = Error setting diffraction parameters.

1 = Success.

getDiffraction

Gets diffraction parameters.

Parameters

Return value

C++

0 = Error getting diffraction parameters.

1 = Success.

Python

Tuple containing all diffraction parameters.

enableDiffraction

Enables diffraction.

Return value

0 = Error enabling diffraction.

1 = Success.

disableDiffraction

Disables diffraction.

Return value

0 = Error disabling diffraction.

1 = Success.

setColorSpace

Sets the output color space used by the render engine.

Parameters

Return value

0 = Error setting color space.

1 = Success.

getColorSpace

Gets the output color space used by the render engine.

Parameters

Return value

Python

Color space used. See COLOR_SPACES enum.

getColorSpaceGamma

Returns the gamma used by the active color space.

getLastError

Returns the latest error occurred, Cerror is defined in error.h. Useful for finding out i/o problems when reading/writing MXS/MXI files.

getLastErrorString

Returns an human readable string containing the latest error occurred.

getDependencies

Returns an array of strings (length and content) with all the extern dependencies of the scene (textures, ior files, hdr files, etc).

Parameters

Return value

C++

0 = Error getting dependencies.

1 = Success.

Python

String list containing all the dependencies.

getObjectsCount

Returns the number of objects in the scene.

Return value

C++

0 = Error getting objects count.

1 = Success.

Python

Number of objects.

getMaterialsCount

Returns the number of materials in the scene.

Return value

C++

0 = Error getting materials count.

1 = Success.

Python

Number of materials.

getCamerasCount

Returns the number of cameras in the scene.

Return value

C++

0 = Error getting cameras count.

1 = Success.

Python

Number of cameras.

getSceneInfo

Returns by reference a CsceneInfo structure with information about the scene.

Return value

C++

0 = Error getting scene info.

1 = Success.

Python

Structure containing the scene info.

computeFresnelGraph

--TODO--

Parameters

Return value

Python

List containing both (pX and pY) vectors as NumPy arrays.

computeAbbeGraph

--TODO--

Parameters

Return value

Python

List containing both (pX and pY) vectors as NumPy arrays.

getCorrelatedColorTemperature

Gets the correlated RGB values given the temperature color.

Return value

C++

0 = Error getting correlated Crgb. i.e. a negative temperature passed as input.

1 = Success.

Python

Crgb color correlated to the temperature color passed as input.

generateUuid

Generates a free uuid useful for storing unique identifiers in scene entities using setUuid() method. The caller owns the pointer passed as argument. It is responsability of the caller to allocate and destroy the passed pointer.

Return value

C++

0 = Error generating unique ID.

1 = Success.

Python

String containing the unique ID.

searchFileInCommonPaths

Looks for the given file in all of the searching paths of the scene.

Parameters

Return value

C++

0 = File not found.

1 = File founded and returned in newFoundFile.

Python

0 = File not found.

String containing found file name.

getEngineVersion

Returns the current version of Maxwell.

getSdkVersion

Returns the current version of the Maxwell SDK.

isDepthSupportedForThisFormat

Returns true if for the given extension the depth is valid. In example:

• isDepthSupportedForThisFormat( "exr", 32 ) returns true.
• isDepthSupportedForThisFormat( "jpg", 16 ) returns false.

getHighestDepthSupportedForThisFormat

Returns the highest bits per plane supported for the given format. In example:

• getHighestDepthSupportedForThisFormat( "exr" ) returns 32.
• getHighestDepthSupportedForThisFormat( "jpg" ) returns 8.

isEmbeddingAlphaSupportedForThisFormat

Returns true if for the given format it is possible embedding the alpha channel.

• isEmbeddingAlphaSupportedForThisFormat( "tga" ) returns true.
• isEmbeddingAlphaSupportedForThisFormat( "jpg" ) returns false.

isEmbeddingAllChannelsSupportedForThisFormat

Returns true if for the given format it is possible embedding all channels in a multilayer file.

• isEmbeddingAllChannelsSupportedForThisFormat( "tif" ) returns true.
• isEmbeddingAllChannelsSupportedForThisFormat( "exr" ) returns true.
• rest of formats : returns false.

isTextureExtensionSupported

Returns true if the extension of the given texture path is supported by the render engine.

getSquareSwatchIES

Used to get the IES/EULUM emission pattern plotted into a square rgb buffer of size "resolution". The caller is responsible of freeing the buffer "buf" after using it.

Parameters

Return value

C++

0 = Error getting IES/EULUM emission pattern.

1 = Success.

Python

List of size = resolution * resolution * 3, containing the RGB emission pattern.

getSolidLobeIES

Used to get the IES/EULUM emission pattern plotted as a 3d object. The caller is responsible of freeing the buffers "faces, points" after using them.

Parameters

Return value

C++

0 = Error getting IES/EULUM 3D emission pattern.

1 = Success.

Python

Tuple containing 'numPoints', 'points', 'numTriangles' and 'faces'.

typeCallback

Callback types of messages given by the rendering callback.

InteractiveFlags

Values of the _interactiveFlags property.