• Confluence is currently running with all non-system plugins disabled, some functionality may be missing
Skip to end of metadata
Go to start of metadata

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

TypeNameDescription
unsigned char_interactiveFlagsInternal use.

Enumerations

typeCallback and InteractiveFlags.

Methods

NameDescription
CmaxwellClass constructor.
~CmaxwellClass destructor.
getMxsVersionGets MXS file version.
getMostRecentVersionMXSGets most recent MXS version supported.
getPluginIDGets the plug-in identifier from which the MXS was created.
setPluginIDGets the plug-in identifier from which the MXS was created.
isProtectionEnabledGets scene protection state in Maxwell Studio (ability to export to other formats).
enableProtectionSets scene protection state in Maxwell Studio (ability to export to other formats).
Scene methods
freeGeometryDeletes all geometry of the scene.
freeSceneResets the scene. Cleans all objects, geometry, materials, etc.
getScenePreviewPreview image of the scene stored in the file (useful for thumbnals).
setScenePreviewSets preview image.
readPreviewSets sene preview image from another MXS.
setInputDataTypeSet the axis orientation of the scene.
setSinglePrecisionOfGeometryUses floats instead of doubles for geometry.
setSceneUserDataInternal use.
addClusterAdds a triangle cluster to the scene.
Object methods
getObjectGets a object reference from the scene.
createMeshCreates a mesh with the given parameters and adds it to the scene.
createInstancementCreates an instancement.
createProxyCreates a proxy object from a MXS.
createRFRKCreates a RealFlow RenderKit object.
addObjectAdds an existent object to the scene.
mergeMeshesMerges meshes into a new one.
Camera methods
addCameraAdds a new camera to the scene with the given parameters.
getCameraGets a camera requested by name.
getActiveCameraGets the active camera of the scene.
Paths methods
setPathSets the path and depth for the given channel.
getPathGets the path and depth for the given channel.
addSearchingPathAdds a path to look for missing textures, ior and ies files.
getSearchingPaths

Gets all searching paths of the scene.

Sky methods
getSunPositionTypeSets sun position type.
setSunPositionTypeGets sun position type.
getSkyConstantGets the parameters of the constant sky.
setSkyConstantSets the parameters of the constant sky.
getSunLongitudeAndLatitudeGets sun longitude and latitude data.
setSunLongitudeAndLatitudeSets sun longitude and latitude data.
getSunAnglesGets sun position angles.
setSunAnglesSets sun position angles.
getSunDirectionGets sun direction vector.
setSunDirectionSets sun direction vector.
getSunRotationGets sun rotation angles.
setSunRotationSets sun rotation angles.
getSunPropertiesGets sun properties
setSunPropertiesSets sun properties.
getPhysicalSkyAtmosphereGets physical atmosphere parameters.
setPhysicalSkyAtmosphereSets physical atmosphere parameters.
getActiveSkyGets active sky name.
setActiveSkySets active sky name.
Additional sky methods
getSunDirectionUsedForRenderingReturns the sun direction.
saveSkyToHDRSaves current sky to an HDR file.
saveSkyToPresetSaves current physical sky values to a file.
loadSkyFromPresetLoads a preset file replacing current physical sky values.
getSkyColorReturns sky RGB color of the current sky values in the given direction.
getSkyColorNoTonemappedReturns sky RGB color (without tonemapping nor exposure) of the current sky values in the given direction.
Environment methods
isEnvironmentEnabledGets IBL (Image Based Lighting) state.
enableEnvironmentSets the IBL (Image Based Lighting) on/off.
getEnvironmentWeightGets the value for the global multiplier of all the environment layers.
setEnvironmentWeightSets the value for the global multiplier of all the environment layers.
getEnvironmentLayerGets the parameters of each environment layer.
setEnvironmentLayerSets the parameters of each environment layer.
Material methods
readMaterialReads a material from file (MXM).
createMaterialCreates a new material.
getMaterialGets a material by name.
addMaterialAdds a material to the scene.
eraseUnusedMaterialsRemove unused materials from the scene.
setOverrideMaterialSets the path and state (enabled/disabled) of the material that overrides all materials of the scene (except emitter materials).
getOverrideMaterialgets the path and state (enabled/disabled) of the material that overrides all materials of the scene (except emitter materials).
setDefaultMaterialSets the path and state (enabled/disabled) of the material that will be used for all the objects/triangles without material.
getDefaultMaterialGets the path and state (enabled/disabled) of the material that will be used for all the objects/triangles without material.
Render methods
setRenderParameterSets render parameter.
getRenderParameterGets render parameter.
Tonemapping methods
getToneMappingGets tonemapping values.
setToneMappingSets tonemapping values.
getActiveToneMappingGets the active tonemapping used ("BASIC" or "ADVANCED" ).
setAdvancedToneMappingDeprecated.
getAdvancedToneMappingDeprecated.
Read/write scene methods
readMXSReads scene from disk.
writeMXSWrites scene to disk.
Glare methods
setDiffractionSets diffraction parameters.
getDiffractionGets diffraction parameters.
enableDiffractionEnables diffraction.
disableDiffractionDisables diffraction.
setColorSpaceSets the output color space used by the render engine.
getColorSpaceGets the output color space used by the render engine.
getColorSpaceGammaReturns the gamma used by the active color space.
Miscellaneous methods
getLastErrorReturns the latest error occurred.
getLastErrorStringReturns an human readable string containing the latest error occurred.
getDependencies

Returns all the extern dependencies of the scene (textures, ior files, hdr files, etc).

getObjectsCountReturns the number of objects in the scene.
getMaterialsCountReturns the number of materials in the scene.
getCamerasCountReturns the number of cameras in the scene.
getTriangleGroupsCountReturns the number of triangle groups in the scene. Deprecated.
getSceneInfoReturns by reference a Cmaxwell::CsceneInfo structure with information about the scene.
computeFresnelGraphComputes the reflectance as a function of the angle of incidence.
computeAbbeGraphComputes the reflectance as a function of the spectral input.
getCorrelatedColorTemperatureGets the correlated RGB values given the temperature color.
generateUuidGenerates an unique ID.
searchFileInCommonPathsLooks for the given file in all of the searching paths of the scene.
createGeometryLoaderObject 
createGeometryProceduralObject 
applySkyExtension 
applySceneModifierExtension 

Static Methods

NameDescription
getEngineVersionReturns the current engine version.
getSdkVersionReturns the current SDK version.
isDepthSupportedForThisFormatReturns true if for the given extension the depth is valid.
getHighestDepthSupportedForThisFormatReturns the highest bits per plane supported for the given format.
isEmbeddingAlphaSupportedForThisFormatReturns true if for the given format it is possible embedding the alpha channel.
isEmbeddingAllChannelsSupportedForThisFormatReturns true if for the given format it is possible embedding all channels in a multilayer file.
isTextureExtensionSupportedReturns 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.

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.

Virtual Methods

NameDescription
printMessagePrints a message in the render console or in the message handler installed.

 

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.

LanguageSyntax

C++

Cmaxwell( byte ( *pCallBack )( byte type, const char* pMethod, const char* pError, const void* pValue ) )
PythonCmaxwell( mwcallback )

Examples

C++
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 );
Python
# PyMaxwell includes a predefined callback function for Cmaxwell constructor called "mwcallback"
 
 pMaxwell = Cmaxwell( mwcallback );

getMxsVersion

Gets MXS file version.

LanguageSyntax
C++float getMxsVersion()
Pythonfloat getMxsVersion()

getMostRecentVersionMXS

Gets most recent MXS version supported.

LanguageSyntax
C++float getMostRecentVersionMXS()
Pythonfloat getMostRecentVersionMXS()

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).

LanguageSyntax
C++const char* getPluginID()
Pythonstr getPluginID()

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).

LanguageSyntax
C++void setPluginID( const char* pID )
Pythonvoid setPluginID( str ID )

isProtectionEnabled

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

LanguageSyntax
C++void isProtectionEnabled( bool& enabled )
Pythonbool isProtectionEnabled()

enableProtection

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

LanguageSyntax
C++void enableProtection( bool enable )
Pythonvoid enableProtection( bool enable )

freeGeometry

Deletes all geometry of the scene.

LanguageSyntax
C++void freeGeometry()
Pythonvoid freeGeometry()

freeScene

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

LanguageSyntax
C++void freeScene()
Pythonvoid freeScene()

getScenePreview

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

LanguageSyntax
C++Crgb8* getScenePreview( dword& xRes, dword& yRes )
Pythonarray getScenePreview()

Parameters

TypeNameIn/OutDescription
dwordxResoutPreview image width.
dwordyResoutPreview image height.

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.

LanguageSyntax
C++byte setScenePreview( dword xRes, dword yRes, Crgb8* pRGB )
Pythonbool setScenePreview( array image )

Parameters

TypeNameIn/OutDescription
dwordxResin(C++) Image width.
dwordyResin(C++) Image height.
Crgb8*pRGBin(C++) Image buffer.
imagearrayin(Python) NumPy ubyte array. Shape is (width,height,3).

Return value

0 = Error setting scene preview image.

1 = Success.

readPreview

Sets the scene preview from another MXS.

LanguageSyntax
C++Crgb8* readPreview( const char* pPath, dword& xResPreview, dword& yResPreview )
Pythonarray readPreview( str filename )

Parameters

TypeNameIn/OutDescription
const char*pPathinMXS file name.
dword&xResPreviewout(C++) Preview width.
dword&yResPreviewout(C++) Preview height.

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.

LanguageSyntax
C++byte setInputDataType( const char* pInput )
Pythonint setInputDataType( str pInput )

Parameters

TypeNameIn/OutDescription
const char*pInputin

Must be one of the following: "YXZ", "ZXY" or "YZX".

Typedefs with plugin names can be used as well:

"YZXRH" = "MAXWELL", "MAYA", "XSI", "HOUDINI", "RHINO" or "SOLIDWORKS".

"ZXYLH" = "FORMZ" or "3DSMAX".

"YXZLH" = "CINEMA".

"YZXLH" = "LIGHTWAVE".

setSinglePrecisionOfGeometry

Uses floats instead of doubles for geometry.

LanguageSyntax
C++void setSinglePrecisionOfGeometry()
Pythonvoid setSinglePrecisionOfGeometry()

addCluster

Creates a triangle cluster in the scene.

LanguageSyntax
C++Cmaxwell::Ccluster addCluster( const char* pName )
PythonCcluster addCluster( pName)

Parameters

TypeNameIn/outDescription
const char*pNameinCluster name

Return value

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

Examples

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

getObject

Gets a object reference from the scene.

LanguageSyntax
C++Cmaxwell::Cobject getObject( const char* pObjectName )
PythonCmaxwellObject getObject( str objectName )

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.

LanguageSyntax
C++Cmaxwell::Cobject createMesh( const char* pName, dword nVertexes, dword nNormals, dword nTriangles, dword nPositionsPerVertex )
PythonCmaxwellObject createMesh( str pName, int nVertexes, int nNormals, int nTriangles, int nPositionsPerVertex )

Parameters

TypeNameIn/OutDescription
const char*pNameinObject name.
dwordnVertexesinNumber of vertexes to create.
dwordnNormalsinNumber of normals to create.
dwordnTrianglesinNumber of triangles to create.
dwordnPositionsPerVertexinSets the number of deformation motion blur substeps (1 or 2, 1 means no deformation blur).

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.

LanguageSyntax
C++Cmaxwell::Cobject createInstancement( const char* pName, Cmaxwell::Cobject& object )
PythonCmaxwellObject createInstancement( str pName, CmaxwellObject object )

Parameters

TypeNameIn/OutDescription
const char*pNameinInstancement name. If exists, an unique name will be assigned, but it is more efficient the user gives an unique name at first.
Cmaxwell::Cobject&objectinCmaxwell::Cobject to be instanced.

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.

LanguageSyntax
C++Cmaxwell::Cobject createProxy( const char* name, const char* proxyPath )
PythonCmaxwellObject createProxy( str name, str proxyPath )

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().

LanguageSyntax
C++Cmaxwell::Cobject createRFRK( const char* objName )
PythonCmaxwellObject createRFRK( str objName )

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.

LanguageSyntax
C++Cmaxwell::Cobject addObject( Cmaxwell::Cobject& object )
PythonCmaxwellObject addObject( CmaxwellObject object )

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() ).

LanguageSyntax
C++Cmaxwell::Cobject mergeMeshes( const char* pName, const Cmaxwell::Cobject* pMeshes, dword nMeshes )
PythonCmaxwellObject mergeMeshes( str pName, CmaxwellObject[] pMeshes )

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

Python
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.

LanguageSyntax
C++

Cmaxwell::Ccamera addCamera( const char *pName, dword nSteps, real shutter, real filmWidth, real filmHeight, real iso, const char *pDiaphragmType, real angle, word nBlades, dword fps, word xRes, dword yRes, real pixelAspect, byte projectionType = 0 );

Python

CmaxwellCamera addCamera( name, nSteps, shutter, filmWidth, filmHeight, iso, diaphragmType, angle, nBlades, fps, xRes, yRes, pixelAspect, proyectionType = 0 )

Parameters

TypeNameIn/OutDescription
const char*pNameinCamera name.
dwordnStepsinNumber of steps.
realshutterinCamera shutter.
realfilmWidthinCamera film width.
realfilmHeitgtinCamera film height.
realisoinCamera ISO.
const char*pDiaphragmTypeinCamera diaphragm type. Must be "CIRCULAR" or "POLYGONAL".
realangleinCamera diaphragm angle.
dwordnBladesinCamera diaphragm blades number.
dwordfpsinFrames per second.
dwordxResinCamera width resolution.
dwordyResinCamera height resolution.
realpixelAspectinPixel aspect.
byteprojectionTypeinCamera projection type. Must be 0 (perspective, default), 1 (front), 2 (top), 3 (left), 4 (back), 5 (bottom), or 6 (right).

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

C++
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 );
Python
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.

LanguageSyntax
C++Cmaxwell::Ccamera getCamera( const char* pCameraName )
PythonCmaxwellCamera getCamera( str cameraName )

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.

LanguageSyntax
C++Cmaxwell::Ccamera getActiveCamera()
PythonCmaxwellCamera getActiveCamera()

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.

LanguageSyntax
C++byte setPath( const char* pType, const char* pPath, byte& outputBitDepthMode )
Pythonint setPath( str pType, str pPath, int outputBitDepthMode )

Parameters

TypeNameIn/OutDescription
const char*pTypeinPath type: "RENDER", "ALPHA", "SHADOW", "OBJECT", "MATERIAL", "MOTION", "Z". ("BITMAPS" is deprecated, use Cmaxwell::addSearchingPath() instead)
const char*pPathinOutput path of the channel.
byteoutputBitDepthModein

Bits depth per pixel (8/16/32). If the depth is not correct for the given format, the engine tries to change this parameter.

i.e. setPath( "image.jpg", 32 ) is not correct because jpg does not support 32 bits so the engine will change it to 8. Get more info about supported image formats.

Return values

0 = Error setting path.

1 = Success.

getPath

Gets path of the given channel.

LanguageSyntax
C++const char* getPath( const char* pType, byte& outputBitDepthMode )
Python(path,outputBitDepthMode) getPath( str pType )

Parameters

TypeNameIn/OutDescription
const char*pTypeinPath type: "RENDER", "ALPHA", "SHADOW", "OBJECT", "MATERIAL", "MOTION", "Z". ("BITMAPS" is deprecated, use Cmaxwell::addSearchingPath() instead)
byteoutputBitDepthModeoutBits depth per pixel (8/16/32).

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.

LanguageSyntax
C++byte addSearchingPath( const char* pPath )
Pythonint addSearchingPath( str pPath )

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).

LanguageSyntax
C++byte getSearchingPaths( dword& numPaths, char**& paths )
Pythonstr[] getSearchingPaths()

Parameters

TypeNameIn/OutDescription
dwordnumPathsoutNumber of paths returned.
char**pathsoutList of paths.

Return value

C++

0 = Error getting searching paths.

1 = Success

Python

List of paths

getSunPositionType

Gets sun positon type.

LanguageSyntax
C++byte getSunPositionType( byte& positionType )
Pythonint getSunPositionType()

Parameters

TypeNameIn/OutDescription
bytepositionTypeoutPosition type: 0 (Latitude/Longitude), 1 (Zenith/azimuth angles) or 2 (Direction vector)

Return value

C++

0 = Error getting sun position type.

1 = Success.

Python

Sun position type.

setSunPositionType

Sets sun position type.

LanguageSyntax
C++byte setSunPositionType( byte& positionType )
Pythonint setSunPositionType( int positionType )

Parameters

TypeNameIn/OutDescription
bytepositionTypeinPosition type: 0 (Latitude/Longitude), 1 (Zenith/azimuth angles) or 2 (Direction vector)

Return value

0 = Error setting sun position type.

1 = Success.

getSkyConstant

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

LanguageSyntax
C++byte getSkyConstant( real& luminance, Crgb& color0, Crgb& color90, real& controlPoint )
Python(float luminance, Crgb color0, Crgb color90, float controlPoint) getSkyConstant()

Parameters

TypeNameIn/OutDescription
realluminanceoutSky luminance. Must be a positive number.
Crgbcolor0outColor at the horizont.
Crgbcolor90outColor at the zenith.
realcontrolPointoutSets the angle where the two colors are 50/50 mixed. i.e controlPoint = 45.0 means that the color at 45º angle is 50% color0 and 50% color90.

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.

LanguageSyntax
C++byte getSkyConstant( real luminance, const Crgb& color0, const Crgb& color90, real controlPoint )
Pythonint getSkyConstant( float luminance, Crgb color0, Crgb color90, float controlPoint )

Parameters

TypeNameIn/OutDescription
realluminanceoutSky luminance. Must be a positive number.
Crgbcolor0outColor at the horizont.
Crgbcolor90outColor at the zenith.
realcontrolPointoutSets the angle where the two colors are 50/50 mixed. i.e controlPoint = 45.0 means that the color at 45º angle is 50% color0 and 50% color90.

Return value

0 = Error setting constant sky parameters.

1 = Success.

getSunLongitudeAndLatitude

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

LanguageSyntax
C++byte getSunLongitudeAndLatitude( real& longitude, real& latitude, int& sm, dword& dayOfYear, real&timeOfDay )
Python

(float longitude, float latitude, int sm, int dayOfYear, int timeOfDay) getSunLongitudeAndLatitude()

Parameters

TypeNameIn/OutDescription
reallongitudeoutLongitude in degrees (from -180.0 to 180.0).
reallatitudeoutLatitude in degrees (from -90.0 to 90.0).
intsmoutGMT.
intdayOfYearoutDay of the year (from 1 to 365, default = 100).
realtimeOfDayoutHour (from 0.0 to 24.0, default = 17.0 ).

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.

LanguageSyntax
C++byte setSunLongitudeAndLatitude( real longitude, real latitude, int sm, dword dayOfYear, real timeOfDay )
Pythonint setSunLongitudeAndLatitude( float longitude, float latitude, int sm, int dayOfYear, float timeOfDay )

Parameters

TypeNameIn/OutDescription
reallongitudeoutLongitude in degrees (from -180.0 to 180.0).
reallatitudeoutLatitude in degrees (from -90.0 to 90.0).
intsmoutGMT.
intdayOfYearoutDay of the year (from 1 to 365, default = 100).
realtimeOfDayoutHour (from 0.0 to 24.0, default = 17.0 ).

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.

LanguageSyntax
C++byte getSunAngles( real& zenith, real& azimuth )
Python(float zenith, float azimuth) getSunAngles()

Parameters

TypeNameIn/outDescription
realzenithoutZenith angle (from 0.0 to PI/2 radians).
realazimuthoutAzimuth angle (from 0.0 to 2PI in radians).

Return values

C++

0 = Error getting sun angles.

1 = Success

Python

Tuple containing zenith and azimuth angles.

Examples

C++
byte ok;
real zenith;
real azimuth;
ok = scene->getSunAngles( zenith, azimuth );
Python
zenith,azimuth = scene.getSunAngles();

setSunAngles

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

LanguageSyntax
C++byte setSunAngles( real zenith, real azimith )
Pythonint setSunAngles( float zenith, float azimuth )

Parameters

TypeNameIn/outDescription
realzenithoutZenith angle (from 0.0 to PI/2 radians).
realazimuthoutAzimuth angle (from 0.0 to 2PI in radians).

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.

LanguageSyntax
C++byte getSunDirection( Cvector3DT& dir )
PythonCvector3DT getSunDirection()

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.

LanguageSyntax
C++byte setSunDirection( Cvector3DT dir )
Pythonint setSunDirection( Cvector3DT dir )

Return value

0 = Error setting sun direction.

1 = Success.

getSunRotation

Gets the ground rotation of the sky hemisphere.

LanguageSyntax
C++byte getSunRotation( real& rotation )
Pythonfloat getSunRotation()

Parameters

TypeNameIn/OutDescription
realrotationoutGround rotation of the sky hemisphere (from 0 to 2PI radians).

Return value

C++

0 = Error getting sun rotation.

1 = Success.

Python

Ground rotation.

setSunRotation

Sets the ground rotation of the sky hemisphere.

LanguageSyntax
C++byte setSunRotation( real rotation )
Pythonint getSunRotation( float rotation )

Parameters

TypeNameIn/OutDescription
realrotationinGround rotation of the sky hemisphere (from 0 to 2PI radians).

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.

LanguageSyntax
C++byte getSunProperties( byte& enabled, real& sunTemperature, real& sunPowerScaleFactor )
Python(int enabled, float sunTemperature, float sunPowerScaleFactor) getSunProperties()

Parameters

TypeNameIn/OutDescription
byteenabledoutSun enabled (1) or disabled (0).
realsunTemperatureoutTemperature in kelvins.
realsunPowerScaleFactoroutTotal power refered to the Earth's sun. For example a value of 0.8 would mean a sun emitting 0.8 times less energy than ours. Default: 1.0. Range: is allowed any value greater than 0.

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.

LanguageSyntax
C++byte setSunProperties( byte enabled, real sunTemperature, real sunPowerScaleFactor )
Pythonint setSunProperties( int enabled, float sunTemperature, float sunPowerScaleFactor )

Parameters

TypeNameIn/OutDescription
byteenabledinSun enabled (1) or disabled (0).
realsunTemperatureinTemperature in kelvins.
realsunPowerScaleFactorinTotal power refered to the Earth's sun. For example a value of 0.8 would mean a sun emitting 0.8 times less energy than ours. Default: 1.0. Range: is allowed any value greater than 0.

Return values

0 = Error setting sun properties.

1 = Success.

getPhysicalSkyAtmosphere

Gets the atmosphere parameters of the physical sky.

LanguageSyntax
C++

byte getPhysicalSkyAtmosphere( real& intensity, real& ozone, real& water, real& angstromTurbidity, real& wavelengthTurbidity, real& aerosolAlbedo, real& asimmetryFactor, real& planetReflectance )

Python

(float intensity, float ozone, float water, float angstromTurbidity, float wavelengthTurbidity, float aerosolAlbedo, float asimmetryFactor, float planetReflectance) getPhysicalSkyAtmosphere()

Parameters

TypeNameIn/OutDescription
realintensityoutIntensity weight. Default: 1.0. Range: Any value greater than 0.
realozoneout(cms) Default: 0.4. Range: Any value greater than 0 (usually between 0 and 1).
realwateroutWater vapor (cms). Default: 2.0. Range: Any value greater than 0.
realangstromTurbidityoutAngstrom turbidity coefficient. Default: 0.04. Range: Any value greater than 0.
realwavelengthTurbidityoutWavelength turbidity exponent. Default 1.2. Range: Any value greater than 0.
realaerosolAlbedooutAerosol albedo. Default 0.8. Range: (0-1).
realasimmetryFactorout"Anisotropy" of aerosol. Default: 0.7. Range (-0.99999, 0.99999).
realplanetReflectanceoutPlanet reflectance. From 0 to 1.

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.

LanguageSyntax
C++

byte setPhysicalSkyAtmosphere( real intensity, real ozone, real water, real angstromTurbidity, real wavelengthTurbidity, real aerosolAlbedo, real asimmetryFactor, real planetReflectance )

Python

byte setPhysicalSkyAtmosphere( float intensity, float ozone, float water, float angstromTurbidity, float wavelengthTurbidity, float aerosolAlbedo, float asimmetryFactor, float planetReflectance )

Parameters

TypeNameIn/OutDescription
realintensityinIntensity weight. Default: 1.0. Range: Any value greater than 0.
realozonein(cms) Default: 0.4. Range: Any value greater than 0 (usually between 0 and 1).
realwaterinWater vapor (cms). Default: 2.0. Range: Any value greater than 0.
realangstromTurbidityinAngstrom turbidity coefficient. Default: 0.04. Range: Any value greater than 0.
realwavelengthTurbidityinWavelength turbidity exponent. Default 1.2. Range: Any value greater than 0.
realaerosolAlbedoinAerosol albedo. Default 0.8. Range: (0-1).
realasimmetryFactorin"Anisotropy" of aerosol. Default: 0.7. Range (-0.99999, 0.99999).
realplanetReflectanceinPlanet reflectance. From 0 to 1.

Return values

0 = Error setting atmosphere parameters.

1 = Success.

getActiveSky

Gets the active sky used.

LanguageSyntax
C++const char* getActiveSky()
Pythonstr getActiveSky()

Return value

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

setActiveSky

Sets the active sky.

LanguageSyntax
C++byte setActiveSky( const char* pActiveSky )
Pythonint setActiveSky( str pActiveSky )

Parameters

TypeNameIn/OutDescription
const char*pActiveSkyinActive sky name. "constant " = constant sky, "physical" = physical sky, NULL = no sky.

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.

LanguageSyntax
C++byte getSunDirectionUsedForRendering( Cvector3DT& dir )
Python

Cvector3DT getSunDirectionUsedForRendering()

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.

LanguageSyntax
C++byte saveSkyToHDR( char* path, const dword& xRes, const dword& yRes )
Pythonint saveSkyToHDR( str path, int xRes, int yRes )

Return value

0 = Error saving HDR.

1 = Success.

saveSkyToPreset

Saves current physical sky values to a sky preset file.

LanguageSyntax
C++byte saveSkyToPreset( const char* path )
Pythonint saveSkyToPreset( str path )

Return value

0 = Error saving sky.

1 = Success.

loadSkyFromPreset

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

LanguageSyntax
C++byte saveSkyToPreset( const char* path )
Pythonint saveSkyToPreset( str path )

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.

LanguageSyntax
C++byte getSkyColor( Crgb& hdrRgb, Crgb8& ldrRgb, const Cvector& dir )
Python(Crgb hdr, Crgb8 ldr) getSkyColor( Cvector dir )

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.

LanguageSyntax
C++byte getSkyColorNoTonemapped( Crgb& hdrRgb, const Cvector& dir )
Pythondict getSkyColorNoTonemapped( Cvector dir )

Return value

C++

0 = Error getting sky color.

1 = Success.

Python

Cvector containing the HDR color.

isEnvironmentEnabled

Gets IBL (Image Based Lighting) state.

LanguageSyntax
C++byte isEnvironmentEnabled( bool& enabled )
Pythonbool isEnvironmentEnabled()

Return value

C++

0 = Error getting IBL state.

1 = Success.

Python

IBL state.

enableEnvironment

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

LanguageSyntax
C++byte enableEnvironment( bool enabled )
Pythonint enableEnvironment( bool enabled )

Return value

0 = Error getting IBL state.

1 = Success.

setEnvironmentWeight

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

LanguageSyntax
C++byte setEnvironmentWeight( real weight )
Pythonint setEnvironmentWeight( float weight )

Return value

0 = Error setting environment weight.

1 = Success.

getEnvironmentWeight

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

LanguageSyntax
C++byte getEnvironmentWeight( real& weight )
Pythonfloat getEnvironmentWeight()

Return value

C++

0 = Error getting IBL state.

1 = Success.

Python

Environment weight.

getEnvironmentLayer

Gets the parameters of each environment layer.

LanguageSyntax
C++byte getEnvironmentLayer( const char* pLayerName, const char*& pBitmapFileName, byte& state, bool& sphericalMapping, bool& interpolate, real& intensity, real& uTile, real& vTile, real& uTileOffset, real& vTileOffset )
Python

(str bitmapFileName, int state, bool sphericalMapping, bool interpolate, float intensity, float uTile, float vTile, float uTileOffset, float TileOffset) getEnvironmentLayer( str pLayerName )

Parameters

TypeNameIn/OutDescription
const char*pLayerNameinSets the layer type. Must be "background", "reflection", "refraction" or "illumination".
const char*pBitmapFileNameoutPath of the texture file.
bytestateoutChannel state: 0 = Disabled; 1 = Enabled; 2 = Use active sky instead. Default: Enabled.
boolsphericalMappingoutSpherical mapping enabled. When pLayerName = "background" must be false.
boolinterpolateoutIf true, pixel values are interpolated.
realintensityoutIntensity range: From 0.0001 to 1000.0 (Default: 1.0).
realuTileoutTile range: From 0.0001 to 1000.0 (default 1.0).
realvTileoutTile range: From 0.0001 to 1000.0 (default 1.0).
realuTileOffsetoutOffset range: From 0.0 to 360.0 (default 0.0).
realvTileOffsetoutOffset range: From 0.0 to 360.0 (default 0.0).

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.

LanguageSyntax
C++byte setEnvironmentLayer( const char* pLayerName, const char* pBitmapFileName, byte state, bool sphericalMapping, bool interpolate, real intensity, real uTile, real vTile, real uTileOffset, real vTileOffset )
Pythonint setEnvironmentLayer( str pLayerName, str pBitmapFilename, int state, bool sphericalMapping, bool interpolate, float intensity, float uTile, float vTile, float uTileOffset, float vTileOffset )

Parameters

TypeNameIn/OutDescription
const char*pLayerNameinSets the layer type. Must be "background", "reflection", "refraction" or "illumination".
const char*pBitmapFileNameinPath of the texture file.
bytestateinChannel state: 0 = Disabled; 1 = Enabled; 2 = Use active sky instead. Default: Enabled.
boolsphericalMappinginSpherical mapping enabled. When pLayerName = "background" must be false.
boolinterpolateinIf true, pixel values are interpolated.
realintensityinIntensity range: From 0.0001 to 1000.0 (Default: 1.0).
realuTileinTile range: From 0.0001 to 1000.0 (default 1.0).
realvTileinTile range: From 0.0001 to 1000.0 (default 1.0).
realuTileOffsetinOffset range: From 0.0 to 360.0 (default 0.0).
realvTileOffsetinOffset range: From 0.0 to 360.0 (default 0.0).

Return value

0 = Error setting environment layer values.

1 = Success.

readMaterial

Reads a material from disk.

LanguageSyntax
C++Cmaxwell::Cmaterial readMaterial( const char* pFileName )
PythonCmaxwellMaterial readMaterial( str pFilename )

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).

LanguageSyntax
C++Cmaxwell::Cmaterial createMaterial( const char* pMaterialName, bool addToScene = true )
PythonCmaxwellMaterial createMaterial( str pMaterialName, bool addToScene = True )

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.

LanguageSyntax
C++Cmaxwell::Cmaterial getMaterial( const char* pMaterialName )
PythonCmaxwellMaterial getMaterial( str pMaterialName )

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.

LanguageSyntax
C++Cmaxwell::Cmaterial addMaterial( Cmaxwell::Cmaterial& material )
PythonCmaxwellMaterial addMaterial( CmaxwellMaterial 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.

LanguageSyntax
C++byte eraseUnusedMaterials()
Pythonint eraseUnusedMaterials()

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).

LanguageSyntax
C++void setOverrideMaterial( const char* pPathMaterial )
 void setOverrideMaterial( bool enabled )
Pythonvoid setOverrideMaterial( str pPathMaterial )
 void setOverrideMaterial( bool enabled )

Parameters

TypeNameIn/OutDescription
const char*pPathMaterialinMXM file name of the override material.
boolenabledinSets override material state (enabled/disabled).

getOverrideMaterial

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

LanguageSyntax
C++const char* getOverrideMaterial()
 void getOverrideMaterial( bool& enabled )
Pythonstr getOverrideMaterial()
 bool getOverrideMaterialEnabled()

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.

LanguageSyntax
C++void setDefaultMaterial( const char* pPathMaterial )
 void setDefaultMaterial( bool enabled )
Pythonvoid setDefaultMaterial( str pPathMaterial )
 void setDefaultMaterial( bool enabled )

Parameters

TypeNameIn/OutDescription
const char*pPathMaterialinMXM file name of the default material.
boolenabledinSets default material state (enabled/disabled).

getDefaultMaterial

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

LanguageSyntax
C++const char* getDefaultMaterial()
 void getDefaultMaterial( bool& enabled )
Pythonstr getDefaultMaterial()
 bool getDefaultMaterialEnabled()

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.

LanguageSyntax
C++byte setRenderParameter( const char* pParameterName, dword size, const void* pParameterValue )
 byte getRenderParameter( const char* pParameterName, dword size, void* pParameterValue )
Pythonint setRenderParameter( str pParameterName, value )
 value getRenderParameter( str pParameterName )

Parameters

TypeNameIn/OutDescription
const char*pParameterNameinParameter name (see pParameterValue for parameter name list).
dwordsizein

Size of the parameter in bytes (see pParameterValue to view sizes by parameter).

Note: parameter size is not needed in Python.

void*pParameterValuein/out

Parameter value, according to the following correspondences:

Parameter nameSizeValue
"ENGINE"sizeof( char ) * 3Selects render engine. "RS0" or "RS1".
"NUM THREADS"sizeof( dword )Number of threads. 0 = automatic.
"STOP TIME"sizeof( dword )Render time in seconds.
"SAMPLING LEVEL"sizeof( float )Target sampling level.
"USE MULTILIGHT"sizeof( byte )0 = No multilight; 1 = Intensity multilight; 2 = Intensity + Color multilight.
"SAVE LIGHTS IN SEPARATE FILES"sizeof( byte )0 = no, 1 = yes.
"MXI FULLNAME"0const char* that specifies the MXI path.
"DO NOT SAVE MXI FILE"sizeof( byte )0 = no, 1 = yes.
"DO NOT SAVE IMAGE FILE"sizeof( byte )0 = no, 1 = yes.
"RENAME AFTER SAVING"sizeof( byte )0 = no, 1 = yes.
"COPY MXI AFTER RENDER"0const char* that specifies the MXI path where output will be copied.
"COPY IMAGE AFTER RENDER"0const char* that specifies the image path where output will be copied.
"REMOVE FILES AFTER COPY"sizeof( byte )0 = no, 1 = yes.
"DO MOTION BLUR"sizeof( byte )0 = no, 1 = yes.
"DO DISPLACEMENT"sizeof( byte )0 = no, 1 = yes.
"DO DISPERSION"sizeof( byte )0 = no, 1 = yes.
"DO DIFFUSE LAYER"sizeof( byte )0 = no, 1 = yes.
"DO REFLECTION LAYER"sizeof( byte )0 = no, 1 = yes.
"DO DIRECT LAYER"sizeof( byte )0 = no, 1 = yes.
"DO INDIRECT LAYER"sizeof( byte )0 = no, 1 = yes.
"DO DIRECT REFLECTION CAUSTIC LAYER"sizeof( byte )0 = no, 1 = yes.
"DO INDIRECT REFLECTION CAUSTIC LAYER"sizeof( byte )0 = no, 1 = yes.
"DO DIRECT REFRACTION CAUSTIC LAYER"sizeof( byte )0 = no, 1 = yes.
"DO INDIRECT REFRACTION CAUSTIC LAYER"sizeof( byte )0 = no, 1 = yes.
"DO RENDER CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO ALPHA CHANNEL"sizeof( byte )0 = no, 1 = yes.
"OPAQUE ALPHA"sizeof( byte )0 = no, 1 = yes.
"EMBED CHANNELS"sizeof( byte )0 = no, 1 = yes.
"DO IDOBJECT CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO IDMATERIAL CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO SHADOW PASS CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO MOTION CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO ROUGHNESS CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO FRESNEL CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO NORMALS CHANNEL"sizeof( byte )0 = no, 1 = yes.
"NORMALS CHANNEL SPACE"sizeof( byte )0 = world space (default ); 1 = camera space.
"POSITION CHANNEL SPACE"sizeof( byte )0 = world space (default ); 1 = camera space.
"MOTION CHANNEL TYPE"sizeof( byte )0 = RealSmart
"DO POSITION CHANNEL"sizeof( byte )0 = no, 1 = yes.
"DO ZBUFFER CHANNEL"sizeof( byte )0 = no, 1 = yes.
"ZBUFFER RANGE"2 * sizeof( real )Two values: z-near and z-far.
"DO DEVIGNETTING"sizeof( byte )0 = no, 1 = yes.
"DEVIGNETTING"sizeof( byte )Devignetting value. Range: 0-100.
"DO SCATTERING_LENS"sizeof( real )Range: 0-1
"DO SHARPNESS"sizeof( byte )0 = no, 1 = yes.
"SHARPNESS"sizeof( byte )Sharpness value. Range: 0-100.

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.

LanguageSyntax
C++byte getToneMapping( real& monitorGamma, real& burn )
Python(float monitorGamma, float burn) getToneMapping()

Return value

C++

0 = Error getting tonemapping value.

1 = Success.

Python

Tuple containing 'monitorGamma' and 'burn' values.

setToneMapping

Sets the tonemapping values.

LanguageSyntax
C++byte setToneMapping( real monitorGamma, real burn )
Pythonint setToneMapping( float monitorGamma, float burn )

Return value

0 = Error setting tonemapping value.

1 = Success.

getActiveToneMapping

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

LanguageSyntax
C++const char* getActiveToneMapping()
Pythonstr getActiveToneMapping()

readMXS

Read scene from disk.

LanguageSyntax
C++byte readMXS( const char* pPath, const Cmaxwell::CoptionsReadMXS& mxsOptions = CoptionsReadMXS() )
Pythonint readMXS( str pPath, CoptionsReadMXS mxsOptions = CoptionsReadMXS() )

Parameters

TypeNameIn/OutDescription
const char*pPathinMXS file name.
Cmaxwell::CoptionsReadMXSmxsOptionsinRead options. Useful to skip, in example, meshes in huge scenes.

Return values

0 = Error reading scene.

1 = Success.

writeMXS

Write the scene to disk.

LanguageSyntax
C++byte writeMXS( const char* pPath = NULL )
Pythonint writeMXS( str pPath )

Return value

0 = Error writing scene to disk.

1 = Success.

setDiffraction

Sets diffraction parameters.

LanguageSyntax
C++byte setDiffraction( real intensity, real frequency, const char* pApperture, const char* pObstacle = NULL )
Pythonint setDiffraction( float intensity, float frequency, str pAperture, str pObstacle = 0 )

Parameters

TypeNameIn/OutDescription
realintensityinDiffraction intensity.
realfrequencyinDiffraction frequency.
const char*pAppertureinDiffraction apperture map path.
const char*pObstacleinDiffraction obstacle map path.

Return value

0 = Error setting diffraction parameters.

1 = Success.

getDiffraction

Gets diffraction parameters.

LanguageSyntax
C++byte getDiffraction( bool& isEnabled, real& intensity, real& frequency, const char** pApperture, const char** pObstacle )
Python

(bool isEnabled, float intensity, float frequence, str aperture, str obstacle) getDiffraction()

Parameters

TypeNameIn/OutDescription
boolisEnabledoutDiffraction state (enabled/disabled).
realintensityoutDiffraction intensity.
realfrequencyoutDiffraction frequency.
const char*pAppertureoutDiffraction apperture map path.
const char*pObstacleoutDiffraction obstacle map path.

Return value

C++

0 = Error getting diffraction parameters.

1 = Success.

Python

Tuple containing all diffraction parameters.

enableDiffraction

Enables diffraction.

LanguageSyntax
C++byte enableDiffraction()
Pythonint enableDiffraction()

Return value

0 = Error enabling diffraction.

1 = Success.

disableDiffraction

Disables diffraction.

LanguageSyntax
C++byte disableDiffraction()
Pythonint disableDiffraction()

Return value

0 = Error disabling diffraction.

1 = Success.

setColorSpace

Sets the output color space used by the render engine.

LanguageSyntax
C++byte setColorSpace( dword type )
Pythonint setColorSpace( int type )

Parameters

TypeNameIn/OutDescription
dwordtypeinColor space selected. See COLOR_SPACES enum.

Return value

0 = Error setting color space.

1 = Success.

getColorSpace

Gets the output color space used by the render engine.

LanguageSyntax
C++void getColorSpace( dword& type )
Pythonint getColorSpace()

Parameters

TypeNameIn/OutDescription
dwordtypeout(C++) Color space used. See COLOR_SPACES enum.

Return value

Python

Color space used. See COLOR_SPACES enum.

getColorSpaceGamma

Returns the gamma used by the active color space.

LanguageSyntax
C++real getColorSpaceGamma()
Pythonfloat getColorSpaceGamma()

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.

LanguageSyntax
C++Cerror::error getLastError()
Pythonint getLastError()

getLastErrorString

Returns an human readable string containing the latest error occurred.

LanguageSyntax
C++const char* getLastErrorString()
Pythonstr getLastErrorString()

getDependencies

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

LanguageSyntax
C++byte getDependencies( dword& numDependencies, char**& paths )
Pythonstr[] getDependencies()

Parameters

TypeNameIn/OutDescription
dwordnumDependenciesoutNumber of dependencies.
char**pathsoutDependencies' file names.

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.

LanguageSyntax
C++byte getObjectsCount( dword& nObjects )
Pythonint getObjectsCount()

Return value

C++

0 = Error getting objects count.

1 = Success.

Python

Number of objects.

getMaterialsCount

Returns the number of materials in the scene.

LanguageSyntax
C++byte getMaterialsCount( dword& nMaterials )
Pythonint getMaterialsCount()

Return value

C++

0 = Error getting materials count.

1 = Success.

Python

Number of materials.

getCamerasCount

Returns the number of cameras in the scene.

LanguageSyntax
C++byte getCamerasCount( dword& nCameras )
Pythonint getCamerasCount()

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.

LanguageSyntax
C++byte getSceneInfo( CsceneInfo& info )
PythonCsceneInfo getSceneInfo()

Return value

C++

0 = Error getting scene info.

1 = Success.

Python

Structure containing the scene info.

computeFresnelGraph

Computes the reflectance as a function of the angle of incidence.

LanguageSyntax
C++void computeFresnelGraph( float* pX, float* pY, dword n, real iorOutgoing )
Pythonarray list[2] computeFresnelGraph( int n, float ioirOutgoing )

Parameters

TypeNameIn/OutDescription
float*pXoutFloat array of size 'n' containing the angle of incidence (from 0 to Pi/2). It must be allocated before call computeFresnelGraph.
float*pYoutFloat array of size 'n' containing the reflectance graph (from 0 to 1). It must be allocated before call computeFresnelGraph.
dwordninSize of pX and pY float vectors.
realiorOutgoinginRefraction index of the material.

Return value

Python

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

computeAbbeGraph

Computes the reflectance as a function of the spectral input.

LanguageSyntax
C++void computeAbbeGraph( float* pX, float* pY, dword n, real nd, real abbe )
Pythonarray list[2] computeAbbeGraph( int n, float nd, float abbe )

Parameters

TypeNameIn/OutDescription
float*pXoutFloat array of size 'n' containing the spectral range (in nm). It must be allocated before call computeAbbeGraph (C++).
float*pYoutFloat array of size 'n' containing the spectral IOR. It must be allocated before call computeAbbeGraph (C++).
dwordninSize of pX and pY float vectors.
realndinRefraction index.
realabbeinAbbe number of the material.

Return value

Python

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

getCorrelatedColorTemperature

Gets the correlated RGB values given the temperature color.

LanguageSyntax
C++byte getCorrelatedColorTemperature( Crgb& rgb, real temperature )
PythonCrgb getCorrelatedColorTemperature( float temperature )

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.

LanguageSyntax
C++byte generateUuid( char** uuid )
Pythonstr generateUuid()

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.

LanguageSyntax
C++byte searchFileInCommonPaths( const char* fileToSearch, char*& newFoundFile )
Pythonstr searchFileInCommonPaths( str fileToSearch )

Parameters

TypeNameIn/OutDescription
const char*fileToSearchinFile to search.
char*newFoundFileoutFile name of the found file.

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.

LanguageSyntax
C++void getEngineVersion( char pVersion[64] )
Pythonstr getEngineVersion()

getSdkVersion

Returns the current version of the Maxwell SDK.

LanguageSyntax
C++void getSdkVersion( char pVersion[64] )
 int getSdkVersion()
Pythonstr getSdkVersionString()
 int getSdkVersion()

isDepthSupportedForThisFormat

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

  • isDepthSupportedForThisFormat( "exr", 32 ) returns true.
  • isDepthSupportedForThisFormat( "jpg", 16 ) returns false.
LanguageSyntax
C++bool isDepthSupportedForThisFormat( const char* extension, byte bitDepth )
Pythonbool isDepthSupportedForThisFormat( str extension, int bitDepth )

getHighestDepthSupportedForThisFormat

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

  • getHighestDepthSupportedForThisFormat( "exr" ) returns 32.
  • getHighestDepthSupportedForThisFormat( "jpg" ) returns 8.
LanguageSyntax
C++byte isDepthSupportedForThisFormat( const char* extension )
Pythonint isDepthSupportedForThisFormat( str extension )

isEmbeddingAlphaSupportedForThisFormat

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

  • isEmbeddingAlphaSupportedForThisFormat( "tga" ) returns true.
  • isEmbeddingAlphaSupportedForThisFormat( "jpg" ) returns false.
LanguageSyntax
C++byte isEmbeddingAlphaSupportedForThisFormat( const char* extension )
Pythonint isEmbeddingAlphaSupportedForThisFormat( str extension )

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.
LanguageSyntax
C++byte isEmbeddingAllChannelsSupportedForThisFormat( const char* extension )
Pythonint isEmbeddingAllChannelsSupportedForThisFormat( str extension )

isTextureExtensionSupported

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

LanguageSyntax
C++byte isTextureExtensionSupported( const char* extension )
Pythonint isTextureExtensionSupported( str extension )

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.

LanguageSyntax
C++byte getSquareSwatchIES( const char* file, int resolution, unsigned char*& buf )
Pythonlist getSquareSwatchIES( str file, int resolution )

Parameters

TypeNameIn/OutDescription
const char*fileinIES/EULUM file name.
intresolutioninResolution requested. Output buffer will have resolution * resolution * 3 values.
unsigned char*&bufoutOutput buffer containing the emission patter.

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.

LanguageSyntax
C++byte getSolidLobeIES( const char* fileName, unsigned int& numPoints, unsigned int& numTriangles, unsigned int*& faces, float*& points, const char* pAxisSystem = NULL )
Python

(int numPoints, list points, int numTriangles, list faces) getSolidLobeIES( str filename, str pAxisSystem = "" )

Parameters

TypeNameIn/OutDescription
const char*fileNameinIES/EULUM file name.
unsigned int&numPointsoutNumber of points returned.
unsigned int&numTrianglesoutNumber of triangles returned.
unsigned int*&facesout0-based indices into points array : v00, v01, v02, v10, v11, v12, .....
float*&pointsoutArray of vertices, x0, y0, z0, x1, y1, z1, .....
const char*pAxisSysteminSame as setInputDataType.

Return value

C++

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

1 = Success.

Python

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

printMessage

Prints a message in the render console or in the message handler installed. Can be reimplemented in subclasses to install handlers.

LanguageSyntax
C++virtual void printMessage( const char* text, const int code )

Parameters

TypeNameIn/OutDescription
const char*textinMessage.
const intcodein

0 = Info.

1 = Error.

2 = Warning.

typeCallback

Callback types of messages given by the rendering callback.

ValueC++Python
0Cmaxwell::CALLBACK_WARNINGCmaxwell.CALLBACK_WARNING
1Cmaxwell::CALLBACK_ERRORCmaxwell.CALLBACK_ERROR
2Cmaxwell::WRITE_USER_DATACmaxwell.WRITE_USER_DATA
3Cmaxwell:READ_USER_DATACmaxwell.READ_USER_DATA

InteractiveFlags

Values of the _interactiveFlags property.

ValueC++Python
0Cmaxwell::ALL_CLEANCmaxwell.ALL_CLEAN
1Cmaxwell::CAMERA_DIRTYCmaxwell.CAMERA_DIRTY
2Cmaxwell::MATERIALS_ASSIGNMENTS_DIRTYCmaxwel.MATERIALS_ASSIGNMENTS_DIRTY
8Cmaxwell::GEOMETRY_DIRTYCmaxwell.GEOMETRY_DIRTY
16Cmaxwell::VOXELIZATION_DIRTYCmaxwell.VOXELIZATION_DIRTY
32Cmaxwell::SKY_OR_HDR_DIRTYCmaxwell.SKY_OR_HDR_DIRTY
64Cmaxwell::DEFAULT_OR_OVERRIDE_MATERIAL_DIRTYCmaxwell.DEFAULT_OR_OVERRIDE_MATERIAL_DIRTY
0x3FCmaxwell::ALL_DIRTYCmaxwell.ALL_DIRTY