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
SUCameraRef Struct Reference

References the camera object of a SketchUp model. More...

`#include <SketchUpAPI/model/camera.h>`

## Related Functions
(Note that these are not member functions.)
enum SUResult | SUCameraCreate (SUCameraRef *camera)
| Creates a default camera object. More...
enum SUResult | SUCameraRelease (SUCameraRef *camera)
| Releases a camera object created by SUCameraCreate. More...
enum SUResult | SUCameraGetOrientation (SUCameraRef camera, struct SUPoint3D *position, struct SUPoint3D *target, struct SUVector3D *up_vector)
| Retrieves the orientation of a camera object. More...
enum SUResult | SUCameraSetOrientation (SUCameraRef camera, const struct SUPoint3D *position, const struct SUPoint3D *target, const struct SUVector3D *up_vector)
| Sets the position of a camera object. More...
enum SUResult | SUCameraGetViewTransformation (SUCameraRef camera, struct SUTransformation *transformation)
| Retrieves the look at matrix of the camera object. More...
enum SUResult | SUCameraSetPerspectiveFrustumFOV (SUCameraRef camera, double fov)
| Sets the field of view angle of a camera object. If the camera object is an orthographic camera, the camera object subsequently becomes a perspective camera. The field of view is measured along the vertical direction of the camera. More...
enum SUResult | SUCameraGetPerspectiveFrustumFOV (SUCameraRef camera, double *fov)
| Retrieves the field of view in degrees of a camera object. The field of view is measured along the vertical direction of the camera. More...
enum SUResult | SUCameraSetAspectRatio (SUCameraRef camera, double aspect_ratio)
| Sets the aspect ratio of a camera object. More...
enum SUResult | SUCameraGetAspectRatio (SUCameraRef camera, double *aspect_ratio)
| Retrieves the aspect ratio of a camera object. More...
enum SUResult | SUCameraSetOrthographicFrustumHeight (SUCameraRef camera, double height)
| Sets the height of a camera object which is used to calculate the orthographic projection of a camera object. If the camera object is a perspective camera, the camera subsequently becomes an orthographic camera. More...
enum SUResult | SUCameraGetOrthographicFrustumHeight (SUCameraRef camera, double *height)
| Retrieves the height of an orthographic camera object. More...
enum SUResult | SUCameraSetPerspective (SUCameraRef camera, bool perspective)
| Sets a camera object perspective or orthographic. More...
enum SUResult | SUCameraGetPerspective (SUCameraRef camera, bool *perspective)
| Retrieves whether a camera object is a perspective camera or not (i.e. orthographic). More...
enum SUResult | SUCameraGetClippingDistances (SUCameraRef camera, double *znear, double *zfar)
| Retrieves the near and far clipping distances of the camera object. More...
enum SUResult | SUCameraSetFOVIsHeight (SUCameraRef camera, bool is_fov_height)
| Sets whether the field of view value represents the camera view height. More...
enum SUResult | SUCameraGetFOVIsHeight (SUCameraRef camera, bool *is_fov_height)
| Retrieves whether the field of view value represents the camera view height. More...
enum SUResult | SUCameraSetImageWidth (SUCameraRef camera, double width)
| Sets the size of the image on the "film" for a perspective camera. The value is given in millimeters. It is used in the conversions between field of view and focal length. More...
enum SUResult | SUCameraGetImageWidth (SUCameraRef camera, double *width)
| Retrieves the size of the image on the image plane of the Camera. By default, this value is not set. If it is set, it is used in the calculation of the focal length from the field of view. Unlike most length values in SketchUp, this width is specified in millimeters rather than in inches. More...
enum SUResult | SUCameraSetDescription (SUCameraRef camera, const char *desc)
| Sets the description of a camera object. More...
enum SUResult | SUCameraGetDescription (SUCameraRef camera, SUStringRef *desc)
| Retrieves the description of a camera object. More...
enum SUResult | SUCameraGetDirection (SUCameraRef camera, struct SUVector3D *direction)
| Retrieves the camera's direction vector. More...
enum SUResult | SUCameraSet2D (SUCameraRef camera, bool make_2d)
| Sets whether a camera is two dimensional. 2 point perspective mode and PhotoMatch mode are 2d cameras. More...
enum SUResult | SUCameraGet2D (SUCameraRef camera, bool *is_2d)
| Retrieves whether a camera object is two dimensional. More...
enum SUResult | SUCameraSetScale2D (SUCameraRef camera, double scale)
| Sets the camera's 2D scale factor. More...
enum SUResult | SUCameraGetScale2D (SUCameraRef camera, double *scale)
| Retrieves the camera's 2D scale factor. More...
enum SUResult | SUCameraSetCenter2D (SUCameraRef camera, const struct SUPoint3D *center)
| Sets the camera's 2D center point. The point coordinates are in screen space. Since this is setting the 2D center point the z component of the provided point is ignored. More...
enum SUResult | SUCameraGetCenter2D (SUCameraRef camera, struct SUPoint3D *center)
| Retrieves the camera's 2D center point. Since this is accessing a 2D point with a 3D point structure the z coordinate is always set to 0.0. More...

## Detailed Description

References the camera object of a SketchUp model.

## Friends And Related Function Documentation

enum SUResult SUCameraCreate | ( | SUCameraRef * | camera | ) |
| related

Creates a default camera object.

Since
  SketchUp 2015, API 3.0

Parameters

  [out] | camera | The camera object created.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if camera is NULL
  - SU_ERROR_OVERWRITE_VALID if camera already refers to a valid object

enum SUResult SUCameraGet2D | ( | SUCameraRef | camera,
|  | bool * | is_2d
| ) |  |
| related

Retrieves whether a camera object is two dimensional.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | is_2d | The 2D flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT is_2d is NULL

enum SUResult SUCameraGetAspectRatio | ( | SUCameraRef | camera,
|  | double * | aspect_ratio
| ) |  |
| related

Retrieves the aspect ratio of a camera object.

Parameters

  [in] | camera | The camera object.
  [out] | aspect_ratio | The aspect ratio retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NO_DATA if the camera uses the screen aspect ratio
  - SU_ERROR_NULL_POINTER_OUTPUT if aspect_ratio is NULL

enum SUResult SUCameraGetCenter2D | ( | SUCameraRef | camera,
|  | struct SUPoint3D * | center
| ) |  |
| related

Retrieves the camera's 2D center point. Since this is accessing a 2D point with a 3D point structure the z coordinate is always set to 0.0.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | center | The center point retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if center is NULL

enum SUResult SUCameraGetClippingDistances | ( | SUCameraRef | camera,
|  | double * | znear,
|  | double * | zfar
| ) |  |
| related

Retrieves the near and far clipping distances of the camera object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | znear | The near clipping distance.
  [out] | zfar | The far clipping distance.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if znear or zfar is NULL

enum SUResult SUCameraGetDescription | ( | SUCameraRef | camera,
|  | SUStringRef * | desc
| ) |  |
| related

Retrieves the description of a camera object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | desc | The description retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera 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 SUCameraGetDirection | ( | SUCameraRef | camera,
|  | struct SUVector3D * | direction
| ) |  |
| related

Retrieves the camera's direction vector.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | direction | The direction vector retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if direction is NULL

enum SUResult SUCameraGetFOVIsHeight | ( | SUCameraRef | camera,
|  | bool * | is_fov_height
| ) |  |
| related

Retrieves whether the field of view value represents the camera view height.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | is_fov_height | The field of view flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT is_fov_height is NULL

enum SUResult SUCameraGetImageWidth | ( | SUCameraRef | camera,
|  | double * | width
| ) |  |
| related

Retrieves the size of the image on the image plane of the Camera. By default, this value is not set. If it is set, it is used in the calculation of the focal length from the field of view. Unlike most length values in SketchUp, this width is specified in millimeters rather than in inches.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | width | The image width retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT width is NULL

enum SUResult SUCameraGetOrientation | ( | SUCameraRef | camera,
|  | struct SUPoint3D * | position,
|  | struct SUPoint3D * | target,
|  | struct SUVector3D * | up_vector
| ) |  |
| related

Retrieves the orientation of a camera object.

Parameters

  [in] | camera | The camera object.
  [out] | position | The position retrieved.
  [out] | target | The target retrieved.
  [out] | up_vector | The up direction retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if position, target, or up_vector is NULL

enum SUResult SUCameraGetOrthographicFrustumHeight | ( | SUCameraRef | camera,
|  | double * | height
| ) |  |
| related

Retrieves the height of an orthographic camera object.

Parameters

  [in] | camera | The camera object.
  [out] | height | The height retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NO_DATA if camera is not an orthographic camera (perspective camera)
  - SU_ERROR_NULL_POINTER_OUTPUT if height is NULL

enum SUResult SUCameraGetPerspective | ( | SUCameraRef | camera,
|  | bool * | perspective
| ) |  |
| related

Retrieves whether a camera object is a perspective camera or not (i.e. orthographic).

Parameters

  [in] | camera | The camera object.
  [out] | perspective | The perspective flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT perspective is NULL

enum SUResult SUCameraGetPerspectiveFrustumFOV | ( | SUCameraRef | camera,
|  | double * | fov
| ) |  |
| related

Retrieves the field of view in degrees of a camera object. The field of view is measured along the vertical direction of the camera.

Parameters

  [in] | camera | The camera object.
  [out] | fov | The field of view retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NO_DATA if camera is not a perspective camera (orthographic camera)
  - SU_ERROR_NULL_POINTER_OUTPUT if fov is NULL

enum SUResult SUCameraGetScale2D | ( | SUCameraRef | camera,
|  | double * | scale
| ) |  |
| related

Retrieves the camera's 2D scale factor.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | scale | The scale factor retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if scale is NULL

enum SUResult SUCameraGetViewTransformation | ( | SUCameraRef | camera,
|  | struct SUTransformation * | transformation
| ) |  |
| related

Retrieves the look at matrix of the camera object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | transformation | The look at matrix retrieved.

Returns
  - SU_ERROR_NONE on success.
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if transformation is NULL

enum SUResult SUCameraRelease | ( | SUCameraRef * | camera | ) |
| related

Releases a camera object created by SUCameraCreate.

Since
  SketchUp 2015, API 3.0

Parameters

  [in] | camera | The camera object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is an invalid object
  - SU_ERROR_NULL_POINTER_INPUT if camera is NULL

enum SUResult SUCameraSet2D | ( | SUCameraRef | camera,
|  | bool | make_2d
| ) |  |
| related

Sets whether a camera is two dimensional. 2 point perspective mode and PhotoMatch mode are 2d cameras.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [in] | make_2d | The flag for specifying if the camera should be 2D.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

enum SUResult SUCameraSetAspectRatio | ( | SUCameraRef | camera,
|  | double | aspect_ratio
| ) |  |
| related

Sets the aspect ratio of a camera object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [out] | aspect_ratio | The aspect ratio to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_OUT_OF_RANGE is aspect_ratio < 0.0

enum SUResult SUCameraSetCenter2D | ( | SUCameraRef | camera,
|  | const struct SUPoint3D * | center
| ) |  |
| related

Sets the camera's 2D center point. The point coordinates are in screen space. Since this is setting the 2D center point the z component of the provided point is ignored.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [in] | center | The center to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if center is NULL

enum SUResult SUCameraSetDescription | ( | SUCameraRef | camera,
|  | const char * | desc
| ) |  |
| related

Sets the description of a camera object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera 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 camera is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if desc is NULL

enum SUResult SUCameraSetFOVIsHeight | ( | SUCameraRef | camera,
|  | bool | is_fov_height
| ) |  |
| related

Sets whether the field of view value represents the camera view height.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [in] | is_fov_height | The field of view flag set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

enum SUResult SUCameraSetImageWidth | ( | SUCameraRef | camera,
|  | double | width
| ) |  |
| related

Sets the size of the image on the "film" for a perspective camera. The value is given in millimeters. It is used in the conversions between field of view and focal length.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [in] | width | The width set in millimeters.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

enum SUResult SUCameraSetOrientation | ( | SUCameraRef | camera,
|  | const struct SUPoint3D * | position,
|  | const struct SUPoint3D * | target,
|  | const struct SUVector3D * | up_vector
| ) |  |
| related

Sets the position of a camera object.

Parameters

  [in] | camera | The camera object.
  [in] | position | The new eye position.
  [in] | target | The new target position.
  [in] | up_vector | The new up direction.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if position, target or up_vector is NULL

enum SUResult SUCameraSetOrthographicFrustumHeight | ( | SUCameraRef | camera,
|  | double | height
| ) |  |
| related

Sets the height of a camera object which is used to calculate the orthographic projection of a camera object. If the camera object is a perspective camera, the camera subsequently becomes an orthographic camera.

Parameters

  [in] | camera | The camera object.
  [in] | height | The height of the camera view.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

enum SUResult SUCameraSetPerspective | ( | SUCameraRef | camera,
|  | bool | perspective
| ) |  |
| related

Sets a camera object perspective or orthographic.

Parameters

  [in] | camera | The camera object.
  [in] | perspective | The perspective flag.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

enum SUResult SUCameraSetPerspectiveFrustumFOV | ( | SUCameraRef | camera,
|  | double | fov
| ) |  |
| related

Sets the field of view angle of a camera object. If the camera object is an orthographic camera, the camera object subsequently becomes a perspective camera. The field of view is measured along the vertical direction of the camera.

Parameters

  [in] | camera | The camera object.
  [in] | fov | The field of view angle in degrees.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

enum SUResult SUCameraSetScale2D | ( | SUCameraRef | camera,
|  | double | scale
| ) |  |
| related

Sets the camera's 2D scale factor.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | camera | The camera object.
  [in] | scale | The scale to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if camera is not a valid object

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

- SketchUpAPI/model/defs.h
- SketchUpAPI/model/camera.h