Used to get and set a scene's camera views, using the SUCameraRef object. More...

#include <SketchUpAPI/model/scene.h>

Related Functions
(Note that these are not member functions.)
SUEntityRef	SUSceneToEntity (SUSceneRef scene)
	Converts from an SUSceneRef to an SUEntityRef. This is essentially an upcast operation. More...

SUSceneRef	SUSceneFromEntity (SUEntityRef entity)
	Converts from an SUEntityRef to an SUSceneRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUSceneRef. More...

enum SUResult	SUSceneCreate (SUSceneRef *scene)
	Creates an empty scene object. More...

enum SUResult	SUSceneRelease (SUSceneRef *scene)
	Releases a scene object. More...

enum SUResult	SUSceneGetUseCamera (SUSceneRef scene, bool *use_camera)
	Retrieves the "use camera" setting of a scene object. More...

enum SUResult	SUSceneSetUseCamera (SUSceneRef scene, bool use_camera)
	Sets the "use camera" setting of a scene object. More...

enum SUResult	SUSceneGetCamera (SUSceneRef scene, SUCameraRef *camera)
	Retrieves the camera of a scene object. The returned camera object points to scene's internal camera. So the camera must not be released via SUCameraRelease(). More...

enum SUResult	SUSceneSetCamera (SUSceneRef scene, SUCameraRef camera)
	Sets a given scene's camera object. The scene does not take ownership of the provided camera, it just copies the properties to the scene's owned camera. If the input camera was created using SUCameraCreate() it must be released using SUCameraRelease(). More...

enum SUResult	SUSceneGetIncludeInAnimation (SUSceneRef scene, bool *include_in_animation)
	Retrieves the "include in animation" setting of a scene object. More...

enum SUResult	SUSceneSetIncludeInAnimation (SUSceneRef scene, bool include_in_animation)
	Sets the "include in animation" setting of a scene object. More...

enum SUResult	SUSceneGetName (SUSceneRef scene, SUStringRef *name)
	Retrieves the name of a scene object. More...

enum SUResult	SUSceneSetName (SUSceneRef scene, const char *scene_name)
	Sets the name of a scene object. More...

enum SUResult	SUSceneGetRenderingOptions (SUSceneRef scene, SURenderingOptionsRef *options)
	Retrieves the rendering options for the scene object. More...

enum SUResult	SUSceneGetShadowInfo (SUSceneRef scene, SUShadowInfoRef *shadow_info)
	Retrieves the shadow info of a scene. More...

enum SUResult	SUSceneGetUseShadowInfo (SUSceneRef scene, bool *use_shadow_info)
	Retrieves the "use shadow info" setting of a scene object. More...

enum SUResult	SUSceneSetUseShadowInfo (SUSceneRef scene, bool use_shadow_info)
	Sets the "use shadow info" setting of a scene object. More...

enum SUResult	SUSceneGetUseRenderingOptions (SUSceneRef scene, bool *use_rendering_options)
	Retrieves the "use rendering options" setting of a scene object. More...

enum SUResult	SUSceneSetUseRenderingOptions (SUSceneRef scene, bool use_rendering_options)
	Sets the "use rendering options" setting of a scene object. More...

enum SUResult	SUSceneGetUseHidden (SUSceneRef scene, bool *use_hidden)
	Gets whether the scene uses the hidden properties of entities. More...

enum SUResult	SUSceneSetUseHidden (SUSceneRef scene, bool use_hidden)
	Sets whether the scene uses the hidden properties of entities. More...

enum SUResult	SUSceneGetUseHiddenGeometry (SUSceneRef scene, bool *use_hidden)
	Gets whether the scene uses the hidden geometry properties of root-level entities. More...

enum SUResult	SUSceneSetUseHiddenGeometry (SUSceneRef scene, bool use_hidden)
	Sets whether the scene uses the hidden properties of root-level entities. More...

enum SUResult	SUSceneGetUseHiddenObjects (SUSceneRef scene, bool *use_hidden)
	Gets whether the scene uses the hidden properties of objects. More...

enum SUResult	SUSceneSetUseHiddenObjects (SUSceneRef scene, bool use_hidden)
	Sets whether the scene uses the hidden properties of objects. More...

enum SUResult	SUSceneGetUseHiddenLayers (SUSceneRef scene, bool *use_hidden_layers)
	Retrieves the "use hidden layers" setting of a scene object. More...

enum SUResult	SUSceneSetUseHiddenLayers (SUSceneRef scene, bool use_hidden_layers)
	Sets the "use hidden layers" setting of a scene object. More...

enum SUResult	SUSceneGetUseSectionPlanes (SUSceneRef scene, bool *use_section_planes)
	Gets whether the scene uses section planes. More...

enum SUResult	SUSceneSetUseSectionPlanes (SUSceneRef scene, bool use_section_planes)
	Sets whether the scene uses section planes. More...

enum SUResult	SUSceneGetNumLayers (SUSceneRef scene, size_t *count)
	Retrieves the number of layers in the scene object. More...

enum SUResult	SUSceneGetLayers (SUSceneRef scene, size_t len, SULayerRef layers[], size_t *count)
	Retrieves the layers in the scene object. More...

enum SUResult	SUSceneAddLayer (SUSceneRef scene, SULayerRef layer)
	Adds the specified layer to the provided scene. More...

enum SUResult	SUSceneRemoveLayer (SUSceneRef scene, SULayerRef layer)
	Removes the specified layer from the provided scene. More...

enum SUResult	SUSceneClearLayers (SUSceneRef scene)
	Removes all of the layers from the provided scene. Scenes do not own their layers so removing them does not release them. More...

enum SUResult	SUSceneGetNumLayerFolders (SUSceneRef scene, size_t *count)
	Retrieves the number of layer folders in the scene object. More...

enum SUResult	SUSceneGetLayerFolders (SUSceneRef scene, size_t len, SULayerFolderRef layer_folders[], size_t *count)
	Retrieves the layer folders in the scene object. More...

enum SUResult	SUSceneAddLayerFolder (SUSceneRef scene, SULayerFolderRef layer_folder)
	Adds the specified layer folder to the provided scene. More...

enum SUResult	SUSceneRemoveLayerFolder (SUSceneRef scene, SULayerFolderRef layer_folder)
	Removes the specified layer folder from the provided scene. More...

enum SUResult	SUSceneClearLayerFolders (SUSceneRef scene)
	Removes all of the layer folders from the provided scene. Scenes do not own their layer folders so removing them does not release them. More...

enum SUResult	SUSceneGetAxes (SUSceneRef scene, SUAxesRef *axes)
	Retrieves the axes of a scene object. More...

enum SUResult	SUSceneSetUseAxes (SUSceneRef scene, bool use_axes)
	Sets the "use axes" setting of a scene object. More...

enum SUResult	SUSceneGetUseAxes (SUSceneRef scene, bool *use_axes)
	Retrieves the "use axes" setting of a scene object. More...

enum SUResult	SUSceneGetNumHiddenEntities (SUSceneRef scene, size_t *count)
	Retrieves the number of hidden entities in the scene object. More...

enum SUResult	SUSceneGetHiddenEntities (SUSceneRef scene, size_t len, SUEntityRef entities[], size_t *count)
	Retrieves the hidden entities in the scene object. More...

enum SUResult	SUSceneSetFlags (SUSceneRef scene, uint32_t flags)
	Sets the flags for a scene object. More...

enum SUResult	SUSceneGetFlags (SUSceneRef scene, uint32_t *flags)
	Retrieves the flags in the scene object. More...

enum SUResult	SUSceneSetSketchAxesDisplayed (SUSceneRef scene, bool displayed)
	Sets the "sketch axes displayed" setting of a scene object. More...

enum SUResult	SUSceneGetSketchAxesDisplayed (SUSceneRef scene, bool *displayed)
	Retrieves the "sketch axes displayed" setting of a scene object. More...

enum SUResult	SUSceneGetPhotoMatchImageDisplayed (SUSceneRef scene, bool *displayed)
	Retrieves the "photo matched image displayed" setting of a scene object. More...

enum SUResult	SUSceneClearPhotoMatchImage (SUSceneRef scene)
	Clears the provided scene's photo match image. More...

enum SUResult	SUSceneGetStyle (SUSceneRef scene, SUStyleRef *style)
	Retrieves the scene's style. More...

enum SUResult	SUSceneCopy (SUSceneRef scene, SUSceneRef copy_scene)
	Copies the data from copy_scene to scene. More...

enum SUResult	SUSceneActivate (SUSceneRef scene)
	Activates the provided scene. More...

enum SUResult	SUSceneSetDrawingElementHidden (SUSceneRef scene, SUDrawingElementRef drawing_element, bool is_hidden)
	Set the visibility of a drawing element in a scene. More...

enum SUResult	SUSceneGetDrawingElementHidden (SUSceneRef scene, SUDrawingElementRef drawing_element, bool *is_hidden)
	Get the visibility of a drawing element in a scene. More...

enum SUResult	SUSceneGetDescription (SUSceneRef scene, SUStringRef *desc)
	Retrieves the description of a scene object. More...

enum SUResult	SUSceneSetDescription (SUSceneRef scene, const char *desc)
	Sets the description of a scene object. More...

enum SUResult	SUSceneSetUseEnvironment (SUSceneRef scene, bool use_environment)
	Enables the use of an environment for a scene. More...

enum SUResult	SUSceneGetUseEnvironment (SUSceneRef scene, bool *use_environment)
	Retrieves the setting whether a scene uses an environment. More...

enum SUResult	SUSceneSetEnvironment (SUSceneRef scene, SUEnvironmentRef environment)
	Sets the environment for a scene. More...

enum SUResult	SUSceneGetEnvironment (SUSceneRef scene, SUEnvironmentRef *environment)
	Retrieves the environment of a scene. More...

enum SUResult	SUSceneGetNumActiveSectionPlanes (SUSceneRef scene, size_t *count)
	Retrieves the number of section planes that will be activated when the scene is activated. More...

enum SUResult	SUSceneGetActiveSectionPlanes (SUSceneRef scene, size_t len, SUSectionPlaneRef active_section_planes[], size_t *count)
	Retrieves the section planes that will be activated when the scene is activated. More...

enum SUResult	SUSceneUpdate (SUSceneRef scene, unsigned int flags)
	Performs an update on the scene properties based on the current view that the use has. More...

Related Functions inherited from SUEntityRef
enum SURefType	SUEntityGetType (SUEntityRef entity)
	Returns the concrete type of the given entity. More...

enum SUResult	SUEntityGetID (SUEntityRef entity, int32_t *entity_id)
	Retrieves the id of the entity. More...

enum SUResult	SUEntityGetPersistentID (SUEntityRef entity, int64_t *entity_pid)
	Retrieves the persistent id of the entity. More...

enum SUResult	SUEntityGetNumAttributeDictionaries (SUEntityRef entity, size_t *count)
	Retrieves the number of attribute dictionaries of an entity. More...

enum SUResult	SUEntityGetAttributeDictionaries (SUEntityRef entity, size_t len, SUAttributeDictionaryRef dictionaries[], size_t *count)
	Retrieves the attribute dictionaries of an entity. More...

enum SUResult	SUEntityAddAttributeDictionary (SUEntityRef entity, SUAttributeDictionaryRef dictionary)
	Adds the attribute dictionary to an entity. The given dictionary object must not belong to another entity. In other words, each dictionary should be added to one entity only. More...

enum SUResult	SUEntityGetAttributeDictionary (SUEntityRef entity, const char name, SUAttributeDictionaryRef dictionary)
	Retrieves the attribute dictionary of an entity that has the given name. More...

enum SUResult	SUEntityGetModel (SUEntityRef entity, SUModelRef *model)
	Retrieves the model object associated with the entity. More...

enum SUResult	SUEntityGetParentEntities (SUEntityRef entity, SUEntitiesRef *entities)
	Retrieves the entities object which contains the entity. More...

Detailed Description

Used to get and set a scene's camera views, using the SUCameraRef object.

Note: Add the scene to the model before setting its properties, except for the name which should be set before adding it.

Friends And Related Function Documentation

enum SUResult SUSceneActivate ( SUSceneRef scene )

Since: SketchUp 2017, API 5.0

Parameters

[in] scene The scene object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneAddLayer	(	SUSceneRef	scene,
		SULayerRef	layer
	)

   Adding a layer to a scene will flag the layer to be the opposite of its
   default scene visibility. See \ref SULayerVisibilityDefaultType. This
   function does not take ownership of the specified layer.

Note: Prior to SketchUp 2020.0, API 8.0 this function did not return SU_ERROR_INVALID_ARGUMENT.

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[in]	layer	The new layer to be added to the scene.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or layer is not a valid object
SU_ERROR_NO_DATA if the scene is not owned by a valid model
SU_ERROR_GENERIC if the scene's model does not contain the layer
SU_ERROR_INVALID_ARGUMENT if the layer already exists in the scene

enum SUResult SUSceneAddLayerFolder	(	SUSceneRef	scene,
		SULayerFolderRef	layer_folder
	)

   Adding a layer folder to a scene will cause that layer folder to be
   flagged as HIDDEN for the specified scene. Any layers or layer folders
   within that layer folder will also be hidden, and therefore don't need to
   be added to the scene. This function does not take ownership of the
   specified layer folder.

Since: SketchUp 2021.0, API 9.0

Parameters

[in]	scene	The scene object.
[in]	layer_folder	The new layer folder to be added to `scene`.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or layer_folder is not a valid object
SU_ERROR_NO_DATA if scene is not owned by a valid model
SU_ERROR_GENERIC if scene's model does not contain layer_folder
SU_ERROR_INVALID_ARGUMENT if layer_folder already exists in scene

enum SUResult SUSceneClearLayerFolders ( SUSceneRef scene )

Since: SketchUp 2021.0, API 9.0

Parameters

[in] scene The scene object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneClearLayers ( SUSceneRef scene )

Since: SketchUp 2016, API 4.0

Parameters

[in] scene The scene object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneClearPhotoMatchImage ( SUSceneRef scene )

Since: SketchUp 2017, API 5.0

Parameters

[in] scene The scene object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneCopy	(	SUSceneRef	scene,
		SUSceneRef	copy_scene
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object to be altered.
[in]	copy_scene	The scene to be copied.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or copy_scene are not a valid objects

enum SUResult SUSceneCreate ( SUSceneRef * scene )

Note: The created scene will not save any scene properties until the SUSceneFlags bits are set.

Parameters

[out] scene The scene object created.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if scene is NULL
SU_ERROR_OVERWRITE_VALID if face already refers to a valid object

See Also: SUSceneSetFlags; SUModelAddScenes

SUScene scene = SU_INVALID;
SUSceneCreate(&scene);
SUSceneSetName(scene, "Example"); // Must be unique.
SUSceneSetFlags(scene, FLAG_USE_ALL); // Set the properties to remember.
SUModelAddScenes(model, 1, &scene); // This will also update the scene based on the flags set.
// Set scene properties after adding it to the model.
// ...
SUSceneSetCamera(scene, eye, target, up);

SUSceneRef SUSceneFromEntity ( SUEntityRef entity )

Parameters

[in] entity The entity reference.

Returns

The converted SUSceneRef if the downcast operation succeeds. If not, the returned reference will be invalid.

enum SUResult SUSceneGetActiveSectionPlanes	(	SUSceneRef	scene,
		size_t	len,
		SUSectionPlaneRef	active_section_planes[],
		size_t *	count
	)

Since: SketchUp 2025.1, API 13.1

Parameters

[in]	scene	The scene object.
[in]	len	The number of section planes to retrieve.
[out]	active_section_planes	The section planes retrieved.
[out]	count	The number of section planes retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if active_section_planes or count is NULL

enum SUResult SUSceneGetAxes	(	SUSceneRef	scene,
		SUAxesRef *	axes
	)

Parameters

[in]	scene	The scene object.
[out]	axes	The axes object retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_INPUT if axes is NULL
SU_ERROR_NO_DATA if the scene is not using axes

enum SUResult SUSceneGetCamera	(	SUSceneRef	scene,
		SUCameraRef *	camera
	)

Parameters

[in]	scene	The scene object.
[out]	camera	The camera object retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_INPUT if camera is NULL

enum SUResult SUSceneGetDescription	(	SUSceneRef	scene,
		SUStringRef *	desc
	)

Since: SketchUp 2022.0, API 10.0

Parameters

[in]	scene	The scene object.
[out]	desc	The description retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is an invalid object
SU_ERROR_NULL_POINTER_OUTPUT if desc is NULL
SU_ERROR_INVALID_OUTPUT if desc does not point to a valid SUStringRef object

enum SUResult SUSceneGetDrawingElementHidden	(	SUSceneRef	scene,
		SUDrawingElementRef	drawing_element,
		bool *	is_hidden
	)

Since: SketchUp 2020, API 8.0

Parameters

[in]	scene	The scene object.
[in]	drawing_element	The drawing element object.
[out]	is_hidden	The current setting for whether or not the drawing element is hidden in the scene.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or drawing_element is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if is_hidden is NULL

enum SUResult SUSceneGetEnvironment	(	SUSceneRef	scene,
		SUEnvironmentRef *	environment
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	scene	The scene object.
[out]	environment	The environment object to be retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if environment is NULL
SU_ERROR_NO_DATA if the scene does not have an environment

enum SUResult SUSceneGetFlags	(	SUSceneRef	scene,
		uint32_t *	flags
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[out]	flags	A bitwise combination of SUSceneFlags.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if flags is NULL

See Also: SUSceneFlags; SUSceneSetFlags

enum SUResult SUSceneGetHiddenEntities	(	SUSceneRef	scene,
		size_t	len,
		SUEntityRef	entities[],
		size_t *	count
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The entities object.
[in]	len	The number of hidden entities to retrieve.
[out]	entities	The hidden entities retrieved.
[out]	count	The number of hidden entities retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if entities or count is NULL

enum SUResult SUSceneGetIncludeInAnimation	(	SUSceneRef	scene,
		bool *	include_in_animation
	)

Since: SketchUp 2018, API 6.0

Parameters

[in]	scene	The scene object.
[out]	include_in_animation	The current setting for whether or not to include in animation.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if include_in_animation is NULL

enum SUResult SUSceneGetLayerFolders	(	SUSceneRef	scene,
		size_t	len,
		SULayerFolderRef	layer_folders[],
		size_t *	count
	)

Since: SketchUp 2021.0, API 9.0

Parameters

[in]	scene	The entities object.
[in]	len	The number of layer_folders to retrieve.
[out]	layer_folders	The layer_folders retrieved.
[out]	count	The number of layer_folders retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if layer_folders or count is NULL

enum SUResult SUSceneGetLayers	(	SUSceneRef	scene,
		size_t	len,
		SULayerRef	layers[],
		size_t *	count
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The entities object.
[in]	len	The number of layers to retrieve.
[out]	layers	The layers retrieved.
[out]	count	The number of layers retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if layers or count is NULL

enum SUResult SUSceneGetName	(	SUSceneRef	scene,
		SUStringRef *	name
	)

Parameters

[in]	scene	The scene object.
[out]	name	The name retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is an invalid object
SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
SU_ERROR_INVALID_OUTPUT if name does not point to a valid SUStringRef object

enum SUResult SUSceneGetNumActiveSectionPlanes	(	SUSceneRef	scene,
		size_t *	count
	)

Since: SketchUp 2025.1, API 13.1

Parameters

[in]	scene	The scene object.
[out]	count	The number of section planes.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUSceneGetNumHiddenEntities	(	SUSceneRef	scene,
		size_t *	count
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[out]	count	The number of hidden entities.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUSceneGetNumLayerFolders	(	SUSceneRef	scene,
		size_t *	count
	)

Since: SketchUp 2021.0, API 9.0

Parameters

[in]	scene	The scene object.
[out]	count	The number of layer folders.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUSceneGetNumLayers	(	SUSceneRef	scene,
		size_t *	count
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[out]	count	The number of layers.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUSceneGetPhotoMatchImageDisplayed	(	SUSceneRef	scene,
		bool *	displayed
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[out]	displayed	The setting retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if displayed is NULL

enum SUResult SUSceneGetRenderingOptions	(	SUSceneRef	scene,
		SURenderingOptionsRef *	options
	)

Parameters

[in]	scene	The scene object.
[out]	options	The options retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is an invalid object
SU_ERROR_NULL_POINTER_OUTPUT if options is NULL
SU_ERROR_NO_DATA if the scene does not use rendering options

enum SUResult SUSceneGetShadowInfo	(	SUSceneRef	scene,
		SUShadowInfoRef *	shadow_info
	)

Since: SketchUp 2015, API 3.0

Parameters

[in]	scene	The scene object.
[out]	shadow_info	The shadow info object retrieved. This object is owned by the scene and must not be explicitly released.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if shadow_info is NULL
SU_ERROR_NO_DATA if the scene does not use shadow info

enum SUResult SUSceneGetSketchAxesDisplayed	(	SUSceneRef	scene,
		bool *	displayed
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[out]	displayed	The setting retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if displayed is NULL

enum SUResult SUSceneGetStyle	(	SUSceneRef	scene,
		SUStyleRef *	style
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[out]	style	The style object retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_INPUT if style is NULL
SU_ERROR_NO_DATA if the scene does not have a style

enum SUResult SUSceneGetUseAxes	(	SUSceneRef	scene,
		bool *	use_axes
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[out]	use_axes	The setting retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_axes is NULL

enum SUResult SUSceneGetUseCamera	(	SUSceneRef	scene,
		bool *	use_camera
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[out]	use_camera	The setting retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_camera is NULL

enum SUResult SUSceneGetUseEnvironment	(	SUSceneRef	scene,
		bool *	use_environment
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	scene	The scene object.
[out]	use_environment	The setting whether a scene should use an environment.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_environment is NULL

enum SUResult SUSceneGetUseHidden	(	SUSceneRef	scene,
		bool *	use_hidden
	)

Since: SketchUp 2018 M0, API 6.0

Deprecated:: The functionality is replaced by SUSceneGetUseHiddenGeometry() and SUSceneGetUseHiddenObjects().

Parameters

[in]	scene	The scene object.
[out]	use_hidden	The current setting for whether or not the hidden property of entities is used.

See Also: SUSceneGetUseHiddenGeometry; SUSceneGetUseHiddenObjects

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_hidden is NULL

enum SUResult SUSceneGetUseHiddenGeometry	(	SUSceneRef	scene,
		bool *	use_hidden
	)

Since: SketchUp 2020.1, API 8.1

Parameters

[in]	scene	The scene object.
[out]	use_hidden	The current setting for whether or not the hidden property of root-level entities is used.

See Also: SUSceneSetUseHiddenGeometry; SUSceneGetUseHiddenObjects; SUSceneSetUseHiddenObjects

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_hidden is NULL

enum SUResult SUSceneGetUseHiddenLayers	(	SUSceneRef	scene,
		bool *	use_hidden_layers
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[out]	use_hidden_layers	The current setting for whether or not hidden layer are used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_hidden_layers is NULL

enum SUResult SUSceneGetUseHiddenObjects	(	SUSceneRef	scene,
		bool *	use_hidden
	)

Since: SketchUp 2020.1, API 8.1

Parameters

[in]	scene	The scene object.
[out]	use_hidden	The current setting for whether or not the hidden property of objects is used.

See Also: SUSceneGetUseHiddenGeometry; SUSceneSetUseHiddenGeometry; SUSceneSetUseHiddenObjects

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_hidden is NULL

enum SUResult SUSceneGetUseRenderingOptions	(	SUSceneRef	scene,
		bool *	use_rendering_options
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[out]	use_rendering_options	The current setting for whether or not rendering options are used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_shadow_info is NULL

enum SUResult SUSceneGetUseSectionPlanes	(	SUSceneRef	scene,
		bool *	use_section_planes
	)

Since: SketchUp 2018 M0, API 6.0

Parameters

[in]	scene	The scene object.
[out]	use_section_planes	The current setting for whether or not section planes property is used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_section_planes is NULL

enum SUResult SUSceneGetUseShadowInfo	(	SUSceneRef	scene,
		bool *	use_shadow_info
	)

Since: SketchUp 2015, API 3.0

Parameters

[in]	scene	The scene object.
[out]	use_shadow_info	The current setting for whether or not shadow info is used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if use_shadow_info is NULL

enum SUResult SUSceneRelease ( SUSceneRef * scene )

Parameters

[in] scene The scene object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is an invalid object
SU_ERROR_NULL_POINTER_INPUT if scene is NULL

enum SUResult SUSceneRemoveLayer	(	SUSceneRef	scene,
		SULayerRef	layer
	)

   Removing a layer from a scene will flag the layer to use its default
   scene visibility. See \ref SULayerVisibilityDefaultType. Scenes do not
   own their layers so removing them doesn't release them.

Note: Prior to SketchUp 2020.0, API 8.0 this function did not return SU_ERROR_INVALID_ARGUMENT.

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[in]	layer	The layer to be removed from the scene.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or layer is not a valid object
SU_ERROR_INVALID_ARGUMENT if the layer doesn't exist in the scene

enum SUResult SUSceneRemoveLayerFolder	(	SUSceneRef	scene,
		SULayerFolderRef	layer_folder
	)

   Removing a layer folder from a scene will cause that layer folder to be
   flagged as VISIBLE for the specified scene. Scenes do not own their layer
   folders so removing them doesn't release them.

Since: SketchUp 2021.0, API 9.0

Parameters

[in]	scene	The scene object.
[in]	layer_folder	The layer folder to be removed from `scene`.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or layer_folder is not a valid object
SU_ERROR_INVALID_ARGUMENT if layer_folder doesn't exist in scene

enum SUResult SUSceneSetCamera	(	SUSceneRef	scene,
		SUCameraRef	camera
	)

Sets a given scene's camera object. The scene does not take ownership of the provided camera, it just copies the properties to the scene's owned camera. If the input camera was created using SUCameraCreate() it must be released using SUCameraRelease().

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[in]	camera	The camera object to be set.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or camera are not a valid objects

enum SUResult SUSceneSetDescription	(	SUSceneRef	scene,
		const char *	desc
	)

Since: SketchUp 2022.0, API 10.0

Parameters

[in]	scene	The scene object.
[in]	desc	The new description for the scene. Assumed to be UTF-8 encoded.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is an invalid object
SU_ERROR_NULL_POINTER_INPUT if desc is NULL

enum SUResult SUSceneSetDrawingElementHidden	(	SUSceneRef	scene,
		SUDrawingElementRef	drawing_element,
		bool	is_hidden
	)

Since: SketchUp 2020, API 8.0

Note: Only drawing elements at the root of the model, or nested instances of components, groups, and images are controlled by scene visibility.

Parameters

[in]	scene	The scene object.
[in]	drawing_element	The drawing element object.
[in]	is_hidden	The new setting for whether or not the drawing element is hidden in the scene.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene or drawing_element is not a valid object or if the drawing_element is geometry in a nested component.

enum SUResult SUSceneSetEnvironment	(	SUSceneRef	scene,
		SUEnvironmentRef	environment
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	scene	The scene object.
[in]	environment	The environment object to be set.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetFlags	(	SUSceneRef	scene,
		uint32_t	flags
	)

Note: If this function is called after the scene has been added to the model the API user must call SUSceneUpdate(). Otherwise it can lead to a crash while interacting with the model. In general it is recommended to use the separate SUSceneSetUse* setters after the scene has been added to the model.; FLAG_USE_HIDDEN is deprecated and the bits for FLAG_USE_HIDDEN_GEOMETRY and FLAG_USE_HIDDEN_OBJECTS will take precedence.

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[in]	flags	A bitwise combination of SUSceneFlags.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

See Also: SUSceneFlags; SUSceneGetFlags; SUSceneUpdate

enum SUResult SUSceneSetIncludeInAnimation	(	SUSceneRef	scene,
		bool	include_in_animation
	)

Since: SketchUp 2018, API 6.0

Parameters

[in]	scene	The scene object.
[in]	include_in_animation	The new setting for whether or not to include in animation.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetName	(	SUSceneRef	scene,
		const char *	scene_name
	)

Warning: Breaking Change: The behavior of SUSceneSetName changed in SketchUp 2018, API 6.0 to return SU_ERROR_INVALID_ARGUMENT if the given name already exists in the scene's model.

Parameters

[in]	scene	The scene object.
[in]	scene_name	The name of the scene object. Assumed to be UTF-8 encoded.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is an invalid object
SU_ERROR_NULL_POINTER_INPUT if scene_name is NULL
SU_ERROR_INVALID_ARGUMENT if the name already exists in the scene's model

enum SUResult SUSceneSetSketchAxesDisplayed	(	SUSceneRef	scene,
		bool	displayed
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[in]	displayed	The new setting for whether or not sketch axes should be displayed.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseAxes	(	SUSceneRef	scene,
		bool	use_axes
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	scene	The scene object.
[in]	use_axes	The new setting for whether or not the axes is used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseCamera	(	SUSceneRef	scene,
		bool	use_camera
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[in]	use_camera	The current setting for whether or not the camera is used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseEnvironment	(	SUSceneRef	scene,
		bool	use_environment
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	scene	The scene object.
[in]	use_environment	The setting whether a scene should use an environment.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseHidden	(	SUSceneRef	scene,
		bool	use_hidden
	)

Since: SketchUp 2018 M0, API 6.0

Deprecated:: The functionality is replaced by SUSceneSetUseHiddenGeometry() and SUSceneSetUseHiddenObjects().

Parameters

[in]	scene	The scene object.
[in]	use_hidden	The new setting for whether or not the hidden property of entities is used.

See Also: SUSceneSetUseHiddenGeometry; SUSceneSetUseHiddenObjects

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseHiddenGeometry	(	SUSceneRef	scene,
		bool	use_hidden
	)

Since: SketchUp 2020.1, API 8.1

Parameters

[in]	scene	The scene object.
[in]	use_hidden	The new setting for whether or not the hidden property of root-level entities is used.

See Also: SUSceneGetUseHiddenGeometry; SUSceneGetUseHiddenObjects; SUSceneSetUseHiddenObjects

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseHiddenLayers	(	SUSceneRef	scene,
		bool	use_hidden_layers
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[in]	use_hidden_layers	The new setting for whether or not hidden layers are used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseHiddenObjects	(	SUSceneRef	scene,
		bool	use_hidden
	)

Since: SketchUp 2020.1, API 8.1

Parameters

[in]	scene	The scene object.
[in]	use_hidden	The new setting for whether or not the hidden property of objects is used.

See Also: SUSceneGetUseHiddenGeometry; SUSceneSetUseHiddenGeometry; SUSceneGetUseHiddenObjects

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseRenderingOptions	(	SUSceneRef	scene,
		bool	use_rendering_options
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	scene	The scene object.
[in]	use_rendering_options	The new setting for whether or not rendering options are used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseSectionPlanes	(	SUSceneRef	scene,
		bool	use_section_planes
	)

Since: SketchUp 2018 M0, API 6.0

Parameters

[in]	scene	The scene object.
[in]	use_section_planes	The new setting for whether or not section planes property is used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

enum SUResult SUSceneSetUseShadowInfo	(	SUSceneRef	scene,
		bool	use_shadow_info
	)

Since: SketchUp 2015, API 3.0

Parameters

[in]	scene	The scene object.
[in]	use_shadow_info	The new setting for whether or not shadow info is used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object

SUEntityRef SUSceneToEntity ( SUSceneRef scene )

Parameters

[in] scene The given scene reference.

Returns

The converted SUEntityRef if scene is a valid object. If not, the returned reference will be invalid.

enum SUResult SUSceneUpdate	(	SUSceneRef	scene,
		unsigned int	flags
	)

What properties of the Scene get updated are controlled via an integer whose bits corresponds to different properties. These flags can be used individually or combined using bitwise OR.

Note: The properties updated is determined by the AND operation of the passed in flags and the flags on the scene set by SUSceneSetFlags() or the separate SUSceneSetUse* setters.

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	scene	The `scene` object.
[in]	flags	The bitwise OR of SUSceneFlags.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if scene is not a valid object
SU_ERROR_INVALID_ARGUMENT if scene is not added to a model

See Also: SUSceneFlags; SUSceneSetFlags

SUScene scene = SU_INVALID;
SUSceneCreate(&scene);
SUSceneSetName(scene, "Example");
SUSceneSetFlags(scene, FLAG_USE_ALL); // Set the properties to remember.
SUModelAddScenes(model, 1, &scene);
// ...
SUSceneUpdate(scene, FLAG_USE_CAMERA | FLAG_USE_SECTION_PLANES);

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

SketchUpAPI/model/defs.h
SketchUpAPI/model/scene.h

Related Functions

Detailed Description

Friends And Related Function Documentation