References an environment, which enables sky boxes and image-based lighting. More...

#include <SketchUpAPI/model/environment.h>

Related Functions
(Note that these are not member functions.)
SUEntityRef	SUEnvironmentToEntity (SUEnvironmentRef environment)
	Converts from an SUEnvironmentRef to an SUEntityRef. This is essentially an upcast operation. More...

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

enum SUResult	SUEnvironmentCreateFromFile (SUEnvironmentRef environment, const char file_path, const char *name)
	Creates an environment object from an SKE, HDR, or EXR file. The image will be loaded into the environment's skydome as a cubemap. More...

enum SUResult	SUEnvironmentWriteToFile (SUEnvironmentRef environment, const char *file_path)
	Writes an environment to an SKE file. More...

enum SUResult	SUEnvironmentRelease (SUEnvironmentRef *environment)
	Releases an environment object and its associated objects. More...

enum SUResult	SUEnvironmentSetName (SUEnvironmentRef environment, const char *name)
	Sets the name of a environment object. More...

enum SUResult	SUEnvironmentGetName (SUEnvironmentRef environment, SUStringRef *name)
	Retrieves the name of a environment object. More...

enum SUResult	SUEnvironmentSetDescription (SUEnvironmentRef environment, const char *desc)
	Sets the description of a environment object. More...

enum SUResult	SUEnvironmentGetDescription (SUEnvironmentRef environment, SUStringRef *desc)
	Retrieves the description of a environment object. More...

enum SUResult	SUEnvironmentSetUseAsSkydome (SUEnvironmentRef environment, bool skydome)
	Sets the the environment to be used as a skydome. More...

enum SUResult	SUEnvironmentGetUseAsSkydome (SUEnvironmentRef environment, bool *skydome)
	Retrieves whether the environment is used as a skydome. More...

enum SUResult	SUEnvironmentSetUseForReflections (SUEnvironmentRef environment, bool reflections)
	Sets the the environment to be used for reflections. More...

enum SUResult	SUEnvironmentGetUseForReflections (SUEnvironmentRef environment, bool *reflections)
	Retrieves whether the environment is used for reflections. More...

enum SUResult	SUEnvironmentSetRotation (SUEnvironmentRef environment, double angle)
	Sets the the environment image vertical rotation angle in degrees. More...

enum SUResult	SUEnvironmentGetRotation (SUEnvironmentRef environment, double *angle)
	Retrieves the environment image rotation in degrees. More...

enum SUResult	SUEnvironmentSetSkydomeExposure (SUEnvironmentRef environment, double exposure)
	Sets the skydome exposure to compensate for variations in HDR image exposure. The unaltered exposure level is `1.0`. More...

enum SUResult	SUEnvironmentGetSkydomeExposure (SUEnvironmentRef environment, double *exposure)
	Retrieves the skydome exposure of the environment. More...

enum SUResult	SUEnvironmentSetReflectionExposure (SUEnvironmentRef environment, double exposure)
	Sets the reflection exposure of the environment. More...

enum SUResult	SUEnvironmentGetReflectionExposure (SUEnvironmentRef environment, double *exposure)
	Retrieves the reflection exposure of the environment. More...

enum SUResult	SUEnvironmentSetLinkedSun (SUEnvironmentRef environment, bool linked_sun)
	Sets the linked sun flag of the environment, enabling the shadow-casting light. Corresponding to "Set Sun Location" in the SketchUp UI. More...

enum SUResult	SUEnvironmentGetLinkedSun (SUEnvironmentRef environment, bool *linked_sun)
	Retrieves whether the environment is linked sun is enabled. More...

enum SUResult	SUEnvironmentSetLinkedSunPosition (SUEnvironmentRef environment, const struct SUPoint2D *position)
	Sets the linked sun position in the environment. More...

enum SUResult	SUEnvironmentGetLinkedSunPosition (SUEnvironmentRef environment, struct SUPoint2D *position)
	Retrieves the linked sun position in the environment. More...

enum SUResult	SUEnvironmentGetThumbnail (SUEnvironmentRef environment, SUImageRepRef *image)
	Retrieves the thumbnail preview image for the given environment. More...

enum SUResult	SUEnvironmentWriteHDRImageToFile (SUEnvironmentRef environment, const char dir_path, SUStringRef full_path_written)
	Writes the HDR image of the environment to a file in its original file type. More...

Detailed Description

References an environment, which enables sky boxes and image-based lighting.

Since: SketchUp 2025.0, API 13.0

Friends And Related Function Documentation

enum SUResult SUEnvironmentCreateFromFile	(	SUEnvironmentRef *	environment,
		const char *	file_path,
		const char *	name
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[out]	environment	The created environment object.
[in]	file_path	The path to the SKE, HDR, or EXR file.
[in]	name	The name of the environment.

Returns

SU_ERROR_NONE on success
SU_ERROR_OVERWRITE_VALID if environment already references a valid object
SU_ERROR_NULL_POINTER_INPUT if file_path , name , or environment is NULL
SU_ERROR_INVALID_ARGUMENT if file_path or name is an empty string
SU_ERROR_SERIALIZATION if the environment could not be created from the file at file_path

SUEnvironmentRef SUEnvironmentFromEntity ( SUEntityRef entity )

Since: SketchUp 2025.0, API 13.0

Parameters

[in] entity The given entity reference.

Returns

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

enum SUResult SUEnvironmentGetDescription	(	SUEnvironmentRef	environment,
		SUStringRef *	desc
	)

Since: SketchUp 2025.0, API 13.0

Parameters

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

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid 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 SUEnvironmentGetLinkedSun	(	SUEnvironmentRef	environment,
		bool *	linked_sun
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	linked_sun	The flag retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if linked_sun is NULL

enum SUResult SUEnvironmentGetLinkedSunPosition	(	SUEnvironmentRef	environment,
		struct SUPoint2D *	position
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	position	The position retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if position is NULL

enum SUResult SUEnvironmentGetName	(	SUEnvironmentRef	environment,
		SUStringRef *	name
	)

Since: SketchUp 2025.0, API 13.0

Parameters

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

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid 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 SUEnvironmentGetReflectionExposure	(	SUEnvironmentRef	environment,
		double *	exposure
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	exposure	The exposure retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if exposure is NULL

enum SUResult SUEnvironmentGetRotation	(	SUEnvironmentRef	environment,
		double *	angle
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	angle	The angle retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if angle is NULL

enum SUResult SUEnvironmentGetSkydomeExposure	(	SUEnvironmentRef	environment,
		double *	exposure
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	exposure	The exposure retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if exposure is NULL

enum SUResult SUEnvironmentGetThumbnail	(	SUEnvironmentRef	environment,
		SUImageRepRef *	image
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	image	The thumbnail to be retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
SU_ERROR_INVALID_OUTPUT if image does not point to a valid SUImageRepRef object
SU_ERROR_NO_DATA if the thumbnail can not be retrieved

enum SUResult SUEnvironmentGetUseAsSkydome	(	SUEnvironmentRef	environment,
		bool *	skydome
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	skydome	The flag retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if skydome is NULL

enum SUResult SUEnvironmentGetUseForReflections	(	SUEnvironmentRef	environment,
		bool *	reflections
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[out]	reflections	The flag retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if reflections is NULL

enum SUResult SUEnvironmentRelease ( SUEnvironmentRef * environment )

Note: An environment object retrieved through SUEnvironmentsRef methods should not be released as it is owned by the model.

Since: SketchUp 2025.0, API 13.0

Parameters

[in,out] environment The environment object.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if environment is NULL
SU_ERROR_INVALID_INPUT if environment does not reference a valid object

enum SUResult SUEnvironmentSetDescription	(	SUEnvironmentRef	environment,
		const char *	desc
	)

Since: SketchUp 2025, API 13.0

Parameters

[in]	environment	The environment object.
[in]	desc	The description to be set. Assumed to be UTF-8 encoded.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_INPUT if desc is NULL

enum SUResult SUEnvironmentSetLinkedSun	(	SUEnvironmentRef	environment,
		bool	linked_sun
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	linked_sun	The flag to set the environment object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object

enum SUResult SUEnvironmentSetLinkedSunPosition	(	SUEnvironmentRef	environment,
		const struct SUPoint2D *	position
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	position	The position to set the environment object. `x` corresponds to longitude with the range `[0.0, 1.0]`, `y` corresponds to latitude with the range `[-1.0, 1.0]`.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_INPUT if position is NULL
SU_ERROR_OUT_OF_RANGE if position has invalid x or y values

enum SUResult SUEnvironmentSetName	(	SUEnvironmentRef	environment,
		const char *	name
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	name	The name string to set the environment object. Assumed to be UTF-8 encoded.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_INPUT if name is NULL
SU_ERROR_INVALID_ARGUMENT if name is an empty string or if no manager is associated with the environment
SU_ERROR_DUPLICATE if name is a duplicate of another environment

enum SUResult SUEnvironmentSetReflectionExposure	(	SUEnvironmentRef	environment,
		double	exposure
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	exposure	The exposure to set the environment object, within the range [0.0, 10.0].

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_OUT_OF_RANGE if exposure is not within the range [0.0, 10.0]

enum SUResult SUEnvironmentSetRotation	(	SUEnvironmentRef	environment,
		double	angle
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	angle	The angle to set the environment object, within the range `[0.0, 360.0)`

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_OUT_OF_RANGE if angle is not within the range [0.0, 360.0)

enum SUResult SUEnvironmentSetSkydomeExposure	(	SUEnvironmentRef	environment,
		double	exposure
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	exposure	The exposure to set the environment object, within the range [0.0, 20.0].

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_OUT_OF_RANGE if exposure is not within the range [0.0, 20.0]

enum SUResult SUEnvironmentSetUseAsSkydome	(	SUEnvironmentRef	environment,
		bool	skydome
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	skydome	The flag to set on the environment object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object

enum SUResult SUEnvironmentSetUseForReflections	(	SUEnvironmentRef	environment,
		bool	reflections
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	reflections	The flag to set the environment object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object

SUEntityRef SUEnvironmentToEntity ( SUEnvironmentRef environment )

Since: SketchUp 2025.0, API 13.0

Parameters

[in] environment The given environment reference.

Returns

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

enum SUResult SUEnvironmentWriteHDRImageToFile	(	SUEnvironmentRef	environment,
		const char *	dir_path,
		SUStringRef *	full_path_written
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object.
[in]	dir_path	The directory path to save the HDR image to.
[out]	full_path_written	The full path of the written file.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_INPUT if dir_path or full_path_written is NULL
SU_ERROR_INVALID_ARGUMENT if dir_path is an empty string
SU_ERROR_SERIALIZATION if the HDR image could not be written to dir_path

enum SUResult SUEnvironmentWriteToFile	(	SUEnvironmentRef	environment,
		const char *	file_path
	)

Since: SketchUp 2025.0, API 13.0

Parameters

[in]	environment	The environment object to write to file.
[in]	file_path	The location to save the environment to. Assumed to be UTF-8 encoded.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if environment is not a valid object
SU_ERROR_NULL_POINTER_INPUT if file_path , name , or environment is NULL
SU_ERROR_INVALID_ARGUMENT if file_path or name is an empty string
SU_ERROR_SERIALIZATION if the environment could not be written to file_path

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

SketchUpAPI/model/defs.h
SketchUpAPI/model/environment.h

Related Functions

Detailed Description

Friends And Related Function Documentation