OpenCMISS-Zinc C++ API Documentation
Public Member Functions | Protected Attributes | List of all members
OpenCMISS::Zinc::Scene Class Reference

Container/manager for graphics visualising a region. More...

#include <scene.hpp>

Public Member Functions

 Scene (cmzn_scene_id scene_id)
 
 Scene (const Scene &scene)
 
Sceneoperator= (const Scene &scene)
 
bool isValid () const
 
cmzn_scene_id getId () const
 
int beginChange ()
 
int endChange ()
 
int convertToPointCloud (const Scenefilter &filter, const Nodeset &nodeset, const Field &coordinateField, double lineDensity, double lineDensityScaleFactor, double surfaceDensity, double surfaceDensityScaleFactor)
 
int convertPointsToNodes (const Scenefilter &filter, const Nodeset &nodeset, const Field &coordinateField)
 
Graphics createGraphics (Graphics::Type graphicsType)
 
GraphicsContours createGraphicsContours ()
 
GraphicsLines createGraphicsLines ()
 
GraphicsPoints createGraphicsPoints ()
 
GraphicsStreamlines createGraphicsStreamlines ()
 
GraphicsSurfaces createGraphicsSurfaces ()
 
Selectionnotifier createSelectionnotifier ()
 
Graphics findGraphicsByName (const char *name)
 
int getCoordinatesRange (const Scenefilter &filter, double *minimumValuesOut3, double *maximumValuesOut3)
 
Graphics getFirstGraphics ()
 
Graphics getNextGraphics (const Graphics &refGraphics)
 
Graphics getPreviousGraphics (const Graphics &refGraphics)
 
int getNumberOfGraphics ()
 
Region getRegion () const
 
Fontmodule getFontmodule ()
 
Glyphmodule getGlyphmodule ()
 
Lightmodule getLightmodule ()
 
Materialmodule getMaterialmodule ()
 
Scenefiltermodule getScenefiltermodule ()
 
Sceneviewermodule getSceneviewermodule ()
 
Spectrummodule getSpectrummodule ()
 
Tessellationmodule getTessellationmodule ()
 
Timekeepermodule getTimekeepermodule ()
 
Field getSelectionField ()
 
int setSelectionField (const Field &selectionField)
 
int getSpectrumDataRange (const Scenefilter &filter, const Spectrum &spectrum, int valuesCount, double *minimumValuesOut, double *maximumValuesOut)
 
int clearTransformation ()
 
bool hasTransformation () const
 
Field getTransformationField () const
 
int setTransformationField (const Field &transformationField)
 
int getTransformationMatrix (double *valuesOut16) const
 
int setTransformationMatrix (const double *valuesIn16)
 
bool getVisibilityFlag ()
 
int setVisibilityFlag (bool visibilityFlag)
 
int moveGraphicsBefore (const Graphics &graphics, const Graphics &refGraphics)
 
int removeAllGraphics ()
 
int removeGraphics (const Graphics &graphics)
 
char * writeDescription ()
 
int readDescription (const char *description, bool overwrite)
 
Scenepicker createScenepicker ()
 
int write (const StreaminformationScene &streaminformationScene)
 
int read (const StreaminformationScene &streaminformationScene)
 
StreaminformationScene createStreaminformationScene ()
 

Protected Attributes

cmzn_scene_id id
 

Detailed Description

Container/manager for graphics visualising a region.

Container/manager for the graphics making up the visualisation of the region's domains and fields.

Member Function Documentation

int OpenCMISS::Zinc::Scene::beginChange ( )
inline

Use this function before making multiple changes on the scene, this will stop scene from executing any immediate changes made in scene. After multiple changes have been made, call the scene end change method to notify clients of changes made up to that point. Can be nested.

See also
Scene::endChange
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Scene::clearTransformation ( )
inline

Clear transformation field or matrix in scene.

Returns
Result OK on success, ERROR_ARGUMENT on failure.
int OpenCMISS::Zinc::Scene::convertPointsToNodes ( const Scenefilter filter,
const Nodeset nodeset,
const Field coordinateField 
)
inline

Creates nodal points in the supplied nodeset sampled points that are in the scene tree (filtered by the optional filter), i.e. including all its descendents. Points/nodes are created with the next available identifier.

Parameters
filterThe filter determining which graphics from the scene tree are converted. If not supplied then all graphics are converted.
nodesetThe nodeset to add nodes to.
coordinateFieldThe coordinate field to be defined and assigned on the new nodes. Must be from the same region as the nodeset.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise some other error code including OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Scene::convertToPointCloud ( const Scenefilter filter,
const Nodeset nodeset,
const Field coordinateField,
double  lineDensity,
double  lineDensityScaleFactor,
double  surfaceDensity,
double  surfaceDensityScaleFactor 
)
inline

Creates a cloud of points (nodes) in the supplied nodeset sampled at random locations according to a Poisson distribution on the lines and surfaces that are in the scene tree (filtered by the optional filter), i.e. including all its descendents. Points/nodes are created with the next available identifier. The density of points is set by supplied arguments and may be scaled by data values stored in each graphics.

Parameters
filterThe filter determining which graphics from the scene tree are converted. If not supplied then all graphics are converted.
nodesetThe nodeset to add nodes to.
coordinateFieldThe coordinate field to be defined and assigned on the new nodes. Must be from the same region as the nodeset.
lineDensityThe expected number of points per unit length for lines.
lineDensity_scale_factorIf a lines graphics has a data field the mean value of its first component multiplied by this factor is added to the expected value.
surfaceDensityThe expected number of points per unit area of surfaces.
surfaceDensity_scale_factorIf a surfaces graphics has a data field the mean value of its first component multiplied by this factor is added to the expected value.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise some other error code including OpenCMISS::Zinc::ERROR_ARGUMENT.
Graphics OpenCMISS::Zinc::Scene::createGraphics ( Graphics::Type  graphicsType)
inline

Create a graphics of the given type in the scene.

Parameters
graphicsTypeEnumerator for a specific graphics type.
Returns
Handle to the new graphics, or NULL/invalid handle on failure.
GraphicsContours OpenCMISS::Zinc::Scene::createGraphicsContours ( )
inline

Create a contours graphics in the scene. Contours create graphics showing where the isoscalar field has fixed value(s): iso-surfaces for 3-D domains, iso-lines for 2-D domains.

Returns
Handle to the new graphics, or NULL/invalid handle on failure.
GraphicsLines OpenCMISS::Zinc::Scene::createGraphicsLines ( )
inline

Create a lines graphics in the scene. Used to visualise 1-D elements and lines/faces of elements.

Returns
Handle to the new graphics, or NULL/invalid handle on failure.
GraphicsPoints OpenCMISS::Zinc::Scene::createGraphicsPoints ( )
inline

Create a points graphics in the scene. Used to visualise static points, nodes, data and sampled element points. Must set the domain type after creation.

See also
Graphics::setFieldDomainType
Returns
Handle to the new graphics, or NULL/invalid handle on failure.
GraphicsStreamlines OpenCMISS::Zinc::Scene::createGraphicsStreamlines ( )
inline

Create a streamlines graphics in the scene.

Returns
Handle to the new graphics, or NULL/invalid handle on failure.
GraphicsSurfaces OpenCMISS::Zinc::Scene::createGraphicsSurfaces ( )
inline

Create a surfaces graphics in the scene. Used to visualise 2-D elements and faces.

Returns
Handle to the new graphics, or NULL/invalid handle on failure.
Scenepicker OpenCMISS::Zinc::Scene::createScenepicker ( )
inline

Create a scene picker which user can use to define a picking volume and find the onjects included in this volume.

Returns
Handle to new scene picker, or NULL/invalid handle on failure.
Selectionnotifier OpenCMISS::Zinc::Scene::createSelectionnotifier ( )
inline

Return a handle to selection notifier for this scene. User can add and remove callback functions from the selection notifier. The callback functions will be called when selection on the scene has changed. Please see selection.h for more details.

Returns
Handle to the new selection notifier, or NULL/invalid handle on failure.
StreaminformationScene OpenCMISS::Zinc::Scene::createStreaminformationScene ( )
inline

Creates a stream information object for specifying files/resources and options for writing scene data from a scene.

Returns
Handle to new stream information, or NULL/invalid handle on failure.
int OpenCMISS::Zinc::Scene::endChange ( )
inline

Call the scene begin change method before making multiple changes on the scene, to stop the scene from notifying clients of every change. After changes have been made, call this method to restart notifications and notify clients of changes made since calling begin change.

See also
Scene::beginChange
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
Graphics OpenCMISS::Zinc::Scene::findGraphicsByName ( const char *  name)
inline

Returns the graphics of the specified name from the scene. Beware that graphics in the same scene may have the same name and this function will only return the first graphics found with the specified name;

Parameters
sceneScene in which to find the graphics.
nameThe name of the graphics to find.
Returns
New reference to graphics of specified name, or 0 if not found. Returns the graphics of the specified name from the scene. Beware that graphics in the same scene may have the same name and this function will only return the first graphics found with the specified name;
Parameters
nameThe name of the graphics to find.
Returns
Handle to first graphics with name, or NULL/invalid handle if not found or failed.
int OpenCMISS::Zinc::Scene::getCoordinatesRange ( const Scenefilter filter,
double *  minimumValuesOut3,
double *  maximumValuesOut3 
)
inline

Get the range of world coordinates spanned by graphics in the scene and its sub-scenes, including application of scene transformation matrices.

Note
Glyph graphics range is not included.
Parameters
filterOptional filter on which graphics to get range from. If omitted, then all graphics within the scene tree contribute.
minimumValuesOut3Array of size 3 to receive the minimum coordinates.
maximumValuesOut3Array of size 3 to receive the maximum coordinates.
Returns
Result OK on success, ERROR_NOT_FOUND if no graphics coordinates found, or any other value on failue.
Graphics OpenCMISS::Zinc::Scene::getFirstGraphics ( )
inline

Get the first graphics on the graphics list of <scene>.

Returns
Handle to first graphics, or NULL/invalid handle if none or failed.
Fontmodule OpenCMISS::Zinc::Scene::getFontmodule ( )
inline

Get the font module which manages fonts for rendering text in graphics.

Returns
Handle to the font module, or NULL/invalid handle on failure.
Glyphmodule OpenCMISS::Zinc::Scene::getGlyphmodule ( )
inline

Get the glyph module which stores static graphics for visualising points, vectors, axes etc. Note on startup no glyphs are defined and glyph module functions need to be called to define standard glyphs.

Returns
Handle to the glyph module, or NULL/invalid handle on failure.
cmzn_scene_id OpenCMISS::Zinc::Scene::getId ( ) const
inline

Return the C handle of the Scene object.

Returns
C handle of Scene if this objects is valid, 0 otherwise.
Lightmodule OpenCMISS::Zinc::Scene::getLightmodule ( )
inline

Return the light module which manages light used to control lighting of the scene. Note on startup only light "default" and "default_ambient" are defined. Additional custom lights can be defined using light module functions.

Returns
Handle to the light module, or NULL/invalid handle on failure.
Materialmodule OpenCMISS::Zinc::Scene::getMaterialmodule ( )
inline

Return the material module which manages materials used to colour, texture and shade graphics. Note on startup only materials "default" and "default_selected" are defined, as white and red, respectively. Additional standard and custom materials can be defined using material module functions.

Returns
Handle to the material module, or NULL/invalid handle on failure.
Graphics OpenCMISS::Zinc::Scene::getNextGraphics ( const Graphics refGraphics)
inline

Get the next graphics after <ref_graphics> on the graphics list of <scene>.

Parameters
refGraphicsHandle to a graphics object.
Returns
Handle to next graphics, or NULL/invalid handle if none or failed.
int OpenCMISS::Zinc::Scene::getNumberOfGraphics ( )
inline

Returns the number of graphics in <scene>.

Returns
Returns the number of graphics in scene.
Graphics OpenCMISS::Zinc::Scene::getPreviousGraphics ( const Graphics refGraphics)
inline

Get the graphics before <ref_graphics> on the graphics list of <scene>.

Parameters
refGraphicsHandle to a graphics object.
Returns
Handle to previous graphics, or NULL/invalid handle if none or failed.
Region OpenCMISS::Zinc::Scene::getRegion ( ) const
inline

Gets the region this scene visualises.

Returns
Handle to owning region, or NULL/invalid handle on failure.
Scenefiltermodule OpenCMISS::Zinc::Scene::getScenefiltermodule ( )
inline

Get the scene filter module which manages scenefilter objects for filtering contents of scenes with scenepicker and sceneviewer etc.

Returns
Handle to the scene filter module, or NULL/invalid handle on failure.
Sceneviewermodule OpenCMISS::Zinc::Scene::getSceneviewermodule ( )
inline

Returns a handle to a sceneviewer module which manages sceneviewer objects for rendering 3-D scenes into rectangular windows or canvases using OpenGL.

Returns
Handle to the sceneviewer module, or NULL/invalid handle on failure.
Field OpenCMISS::Zinc::Scene::getSelectionField ( )
inline

Get the selection field for the scene, if any.

Returns
Handle to selection field, or NULL/invalid handle if none or failed.
int OpenCMISS::Zinc::Scene::getSpectrumDataRange ( const Scenefilter filter,
const Spectrum spectrum,
int  valuesCount,
double *  minimumValuesOut,
double *  maximumValuesOut 
)
inline

Get the range of graphics data field values rendered with the spectrum. Search is limited to the scene and its sub-scenes with an optional filter. Spectrum colour bar glyphs do not contribute to the range.

Parameters
filterOptional filter on which graphics to get data range from. If omitted, then all graphics within the scene tree contribute.
spectrumThe spectrum to get the range for. Only data for graphics using this spectrum contribute to the range.
valuesCountThe number of data values to get the minimum and maximum range for, at least 1.
minimumValuesOutArray to receive the data value minimums. Must be at least as large as valuesCount.
maximumValuesOutArray to receive the data value maximums. Must be at least as large as valuesCount.
Returns
The number of data components for which a valid range is obtainable, which can be more or less than the valuesCount so must be tested if more than one component range requested. Returns 0 on any other error including bad arguments.
Spectrummodule OpenCMISS::Zinc::Scene::getSpectrummodule ( )
inline

Get the spectrum module which manages spectrum objects controlling how graphics data fields are converted into colours.

Returns
Handle to the spectrum module, or NULL/invalid handle on failure.
Tessellationmodule OpenCMISS::Zinc::Scene::getTessellationmodule ( )
inline

Get the tessellation module which manages objects controlling how curves are approximated by line segments in graphics.

Returns
Handle to the tessellation module, or NULL/invalid handle on failure.
Timekeepermodule OpenCMISS::Zinc::Scene::getTimekeepermodule ( )
inline

Get the timekeeper module which manages objects for synchronising time across zinc objects.

Returns
Handle to the timekeeper module, or NULL/invalid handle on failure.
Field OpenCMISS::Zinc::Scene::getTransformationField ( ) const
inline

Get optional field providing the 4x4 transformation of the scene local coordinates into the parent scene local coordinate system, or world coordinate system if scene is for the root region.

See also
Scene::setTransformationField
Returns
Handle to field, or NULL/invalid handle if none or failed.
int OpenCMISS::Zinc::Scene::getTransformationMatrix ( double *  valuesOut16) const
inline

Get 4x4 transformation matrix of the scene local coordinates into the parent scene local coordinate system, or world coordinate system if scene is for the root region. If a transformation field is active, calculates the current transformation matrix from the field, or returns an error if the field cannot be evaluated. If no transformation is active this function returns the 4x4 identity matrix.

See also
Scene::setTransformationMatrix
Scene::setTransformationField
Parameters
valuesOut16An array large enough to fill with the 16 components of the transformation matrix.
Returns
Result OK on success, any other value on failure.
bool OpenCMISS::Zinc::Scene::getVisibilityFlag ( )
inline

Returns the state of the scene's visibility flag.

Returns
Boolean value true if visibility flag is set, false if not.
bool OpenCMISS::Zinc::Scene::hasTransformation ( ) const
inline

Query whether scene has either a transformation field or matrix active.

Returns
True scene has transformation, false if not or invalid scene.
bool OpenCMISS::Zinc::Scene::isValid ( ) const
inline

Check if this is a valid Scene object.

Returns
Status True if object is valid, false otherwise.
int OpenCMISS::Zinc::Scene::moveGraphicsBefore ( const Graphics graphics,
const Graphics refGraphics 
)
inline

Move a graphics to the position before ref_graphics in the scene's graphics list, or last in the list if no reference graphics supplied. Earlier graphics are drawn first and in hardware rendering their pixel fragments are displayed in priority over later graphics at the same depth.

Parameters
graphicsThe graphics to be moved. Must be from scene.
refGraphicsAnother graphics from this scene to insert before, or NULL to move graphics to last position in list.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Scene::read ( const StreaminformationScene streaminformationScene)
inline

Import graphics data to scene described in the stream information object.

See also
Scene::createStreaminformationScene
Parameters
streaminformationSceneHandle to the stream information scene containing stream resources.
Returns
Status OpenCMISS::Zinc::OK if data is successfully imported, any other value on failure.
int OpenCMISS::Zinc::Scene::readDescription ( const char *  description,
bool  overwrite 
)
inline

Read the json description to the scene and graphics. This will change the settings in scene and its graphics.

The string containing json description old graphics will be replaced when set to true or new graphics will be added to the existing graphics when set to false

Returns
OpenCMISS::Zinc::OK on success, otherwise ERROR status.
int OpenCMISS::Zinc::Scene::removeAllGraphics ( )
inline

Removes all graphics from the scene.

Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Scene::removeGraphics ( const Graphics graphics)
inline

Removes a graphics from scene and decrements the position of all subsequent graphics.

Parameters
graphicsThe graphics to be removed.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Scene::setSelectionField ( const Field selectionField)
inline

Set the field giving selection and highlighting in the scene. Currently restricted to 'field_group' type fields. This function will also set the selection field for all of its subregion scenes if the a corresponding subregion field_group exists, otherwise the selection group of the child scene will be set to NULL.

Parameters
selectionFieldGroup field to be used as the selection.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Scene::setTransformationField ( const Field transformationField)
inline

Set optional field providing the 4x4 transformation of the scene local coordinates into the parent scene local coordinate system, or world coordinate system if scene is for the root region. Overrides any current scene transformation matrix.

See also
Scene::setTransformationMatrix
Parameters
transformationFieldA 16 component field whose values give a 4x4 transformation of homogeneous coordinates, or NULL/invalid to clear transformation. This field must be spatially constant, but it may be time-varying in which case scene redraws are automatically triggered when the time changes. Runtime errors will be reported if this field cannot be evaluated given only the current timekeeper time. Field must belong to this scene's owning region.
Returns
Result OK on success, any other value on failure.
int OpenCMISS::Zinc::Scene::setTransformationMatrix ( const double *  valuesIn16)
inline

Set fixed 4x4 transformation matrix of the scene local coordinates into the parent scene local coordinate system, or world coordinate system if scene is for the root region. Clears any current scene transformation field.

The 16 components give the following matrix transformation:

    |x.out| = | c01 c02 c03 c04 | |x.in|
    |y.out| = | c05 c05 c07 c08 | |y.in|
    |z.out| = | c09 c10 c11 c12 | |z.in|
    |h.out| = | c13 c14 c15 c16 | |h.in|

where 'in' coordinates are local coordinates in the scene, and 'out' coordinates are in the parent local or world coordinate system. Homogeneous coordinates are used after division by the h component which gives a perspective effect if not equal to 1. Typical no-perspective usage uses h.in=1 and the bottom row 0 0 0 1 so h.out=1, hence c04, c08, c12 give displacement and the upper-left 3x3 matrix defines basis vectors of local coordinates in terms of parent coordinates.

Parameters
valuesIn16An array of 16 values giving the 4x4 transformation matrix.
Returns
Result OK on success, any other value on failure.
int OpenCMISS::Zinc::Scene::setVisibilityFlag ( bool  visibilityFlag)
inline

Set the state of the scene's visibility flag. Note this only affects visibility of graphics when a scene filter is acting on it.

Parameters
visibilityFlagBoolean true to set, false to clear.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Scene::write ( const StreaminformationScene streaminformationScene)
inline

Writes graphics data in scene to stream resource objects described in the stream information object.

See also
Scene::createStreaminformationScene
Parameters
streaminformationSceneHandle to the stream information scene containing information about resources to write to.
Returns
Status OpenCMISS::Zinc::OK if data is successfully written out, any other value on failure.
char* OpenCMISS::Zinc::Scene::writeDescription ( )
inline

Write the json file describing the scene and its graphics, which can be used to store the current scene settings.

Returns
c string containing the json description of scene, otherwise 0;

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