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

#include <scene.hpp>

Public Member Functions
	Scene (cmzn_scene_id scene_id)

	Scene (const Scene &scene)

Scene &	operator= (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

filter	The filter determining which graphics from the scene tree are converted. If not supplied then all graphics are converted.
nodeset	The nodeset to add nodes to.
coordinateField	The 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

filter	The filter determining which graphics from the scene tree are converted. If not supplied then all graphics are converted.
nodeset	The nodeset to add nodes to.
coordinateField	The coordinate field to be defined and assigned on the new nodes. Must be from the same region as the nodeset.
lineDensity	The expected number of points per unit length for lines.
lineDensity_scale_factor	If a lines graphics has a data field the mean value of its first component multiplied by this factor is added to the expected value.
surfaceDensity	The expected number of points per unit area of surfaces.
surfaceDensity_scale_factor	If 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

graphicsType Enumerator 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

scene	Scene in which to find the graphics.
name	The 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

name	The 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

filter	Optional filter on which graphics to get range from. If omitted, then all graphics within the scene tree contribute.
minimumValuesOut3	Array of size 3 to receive the minimum coordinates.
maximumValuesOut3	Array 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

refGraphics Handle 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

refGraphics Handle 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

filter	Optional filter on which graphics to get data range from. If omitted, then all graphics within the scene tree contribute.
spectrum	The spectrum to get the range for. Only data for graphics using this spectrum contribute to the range.
valuesCount	The number of data values to get the minimum and maximum range for, at least 1.
minimumValuesOut	Array to receive the data value minimums. Must be at least as large as valuesCount.
maximumValuesOut	Array 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

valuesOut16 An 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

graphics	The graphics to be moved. Must be from scene.
refGraphics	Another 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

streaminformationScene Handle 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

graphics The 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

selectionField Group 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

transformationField A 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

valuesIn16 An 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

visibilityFlag Boolean 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

streaminformationScene Handle 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:

auto_comments_output/scene.hpp
auto_comments_output/scenepicker.hpp
auto_comments_output/sceneviewer.hpp
auto_comments_output/streamscene.hpp

Public Member Functions

Protected Attributes

Detailed Description

Member Function Documentation