SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUEnvironmentRef Struct Reference

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 or SKE file 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
| ) |  |
| related

Creates an environment object from an SKE, HDR, or EXR file. The image or SKE file will be loaded into the environment's skydome as a cubemap.

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. If empty, the name will default to the name stored in the SKE file (if available), or to the file name.

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` is an empty string
  - SU_ERROR_SERIALIZATION if the `environment` could not be created from the file at `file_path`

SUEnvironmentRef SUEnvironmentFromEntity | ( | SUEntityRef | entity | ) |
| related

Converts from an SUEntityRef to an SUEnvironmentRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUEnvironmentRef.

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

Retrieves the description of a environment object.

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

Retrieves whether the environment is linked sun is enabled.

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

Retrieves the linked sun position in the environment.

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

Retrieves the name of a environment object.

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

Retrieves the reflection exposure of the environment.

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

Retrieves the environment image rotation in degrees.

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

Retrieves the skydome exposure of the environment.

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

Retrieves the thumbnail preview image for the given environment.

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

Retrieves whether the environment is used as a 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
| ) |  |
| related

Retrieves whether the environment is used for 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 | ) |
| related

Releases an environment object and its associated objects.

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

Sets the description of a environment object.

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

Sets the linked sun flag of the environment, enabling the shadow-casting light. Corresponding to "Set Sun Location" in the SketchUp UI.

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

Sets the linked sun position in the environment.

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

Sets the name of a environment object.

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

Sets the reflection exposure of the environment.

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

Sets the the environment image vertical rotation angle in degrees.

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

Sets the skydome exposure to compensate for variations in HDR image exposure. The unaltered exposure level is `1.0`.

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

Sets the the environment to be used as a 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
| ) |  |
| related

Sets the the environment to be used for 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 | ) |
| related

Converts from an SUEnvironmentRef to an SUEntityRef. This is essentially an upcast operation.

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

Writes the HDR image of the environment to a file in its original file type.

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

Writes an environment to an SKE file.

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