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

References an image object. More...

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

Inherits SUDrawingElementRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUImageToEntity (SUImageRef image)
| Converts from an SUImageRef to an SUEntityRef. This is essentially an upcast operation. More...
SUImageRef | SUImageFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUImageRef. This is essentially a downcast operation so the given entity must be convertible to an SUImageRef. More...
SUDrawingElementRef | SUImageToDrawingElement (SUImageRef image)
| Converts from an SUImageRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
SUImageRef | SUImageFromDrawingElement (SUDrawingElementRef drawing_elem)
| Converts from an SUDrawingElementRef to an SUImageRef. This is essentially a downcast operation so the given element must be convertible to an SUImageRef. More...
enum SUResult | SUImageCreateFromFile (SUImageRef *image, const char *file_path)
| Creates a new image object from an image file specified by a path. The created image must be subsequently added to the Entities of a model, component definition or a group. Use SUModelRemoveComponentDefinitions() to remove the image from a model. More...
enum SUResult | SUImageCreateFromImageRep (SUImageRef *image, SUImageRepRef image_rep)
| Creates a new SketchUp model image object from an image representation object. The created image must be subsequently added to the Entities of a model, component definition or a group. Use SUModelRemoveComponentDefinitions() to remove the image from a model. More...
enum SUResult | SUImageGetImageRep (SUImageRef image, SUImageRepRef *image_rep)
| Retrieves a basic image from a SketchUp model image. The given image representation object must have been constructed using one of the SUImageRepCreate* functions. It must be released using SUImageRepRelease(). afterwards. More...
enum SUResult | SUImageGetName (SUImageRef image, SUStringRef *name)
| Retrieves the name of an image object. More...
enum SUResult | SUImageSetName (SUImageRef image, const char *name)
| Sets the name of an image object. More...
enum SUResult | SUImageGetTransform (SUImageRef image, struct SUTransformation *transform)
| Retrieves the 3-dimensional homogeneous transform of an image object. More...
enum SUResult | SUImageSetTransform (SUImageRef image, const struct SUTransformation *transform)
| Sets the 3-dimensional homogeneous transform of an image object. More...
enum SUResult | SUImageGetFileName (SUImageRef image, SUStringRef *file_name)
| Retrieves the image file name of an image object. More...
enum SUResult | SUImageGetDimensions (SUImageRef image, double *width, double *height)
| Retrieves the world dimensions of an image object. More...
enum SUResult | SUImageGetDefinition (SUImageRef image, SUComponentDefinitionRef *component)
| Retrieves the component definition of an image object. More...
enum SUResult | SUImageGetPixelDimensions (SUImageRef image, size_t *width, size_t *height)
| Retrieves the width and height dimensions of an image object in pixels. More...
enum SUResult | SUImageGetDataSize (SUImageRef image, size_t *data_size, size_t *bits_per_pixel)
| Returns the total size and bits-per-pixel value of an image. This function is useful to determine the size of the buffer necessary to be passed into SUImageGetData(). The returned data can be used along with the returned bits-per-pixel value and the image dimensions to compute RGBA values at individual pixels of the image. More...
enum SUResult | SUImageGetData (SUImageRef image, size_t data_size, SUByte pixel_data[])
| Returns the pixel data for an image. The given array must be large enough to hold the image's data. This size can be obtained by calling SUImageGetDataSize(). More...
Related Functions inherited from SUDrawingElementRef
SUEntityRef | SUDrawingElementToEntity (SUDrawingElementRef elem)
| Converts from an SUDrawingElementRef to an SUEntityRef. This is essentially an upcast operation. More...
SUDrawingElementRef | SUDrawingElementFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUDrawingElementRef. This is essentially a downcast operation so the given entity must be convertible to a drawing element. More...
enum SURefType | SUDrawingElementGetType (SUDrawingElementRef elem)
| Returns the concrete type of the given drawing element. More...
enum SUResult | SUDrawingElementGetBoundingBox (SUDrawingElementRef elem, struct SUBoundingBox3D *bbox)
| Retrieves the bounding box of a drawing element. More...
enum SUResult | SUDrawingElementGetMaterial (SUDrawingElementRef elem, SUMaterialRef *material)
| Retrieves the material object of a drawing element. More...
enum SUResult | SUDrawingElementSetMaterial (SUDrawingElementRef elem, SUMaterialRef material)
| Sets the material of a drawing element. More...
enum SUResult | SUDrawingElementGetLayer (SUDrawingElementRef elem, SULayerRef *layer)
| Retrieves the layer object associated with a drawing element. More...
enum SUResult | SUDrawingElementSetLayer (SUDrawingElementRef elem, SULayerRef layer)
| Sets the layer object to be associated with a drawing element. More...
enum SUResult | SUDrawingElementSetHidden (SUDrawingElementRef elem, bool hide_flag)
| Sets the hide flag of a drawing element. More...
enum SUResult | SUDrawingElementGetHidden (SUDrawingElementRef elem, bool *hide_flag)
| Retrieves the hide flag of a drawing element. More...
enum SUResult | SUDrawingElementSetCastsShadows (SUDrawingElementRef elem, bool casts_shadows_flag)
| Sets the casts shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementGetCastsShadows (SUDrawingElementRef elem, bool *casts_shadows_flag)
| Retrieves the casts shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementSetReceivesShadows (SUDrawingElementRef elem, bool receives_shadows_flag)
| Sets the receives shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementGetReceivesShadows (SUDrawingElementRef elem, bool *receives_shadows_flag)
| Retrieves the receives shadows flag of a drawing element. 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

References an image object.

## Friends And Related Function Documentation

enum SUResult SUImageCreateFromFile | ( | SUImageRef * | image,
|  | const char * | file_path
| ) |  |
| related

Creates a new image object from an image file specified by a path. The created image must be subsequently added to the Entities of a model, component definition or a group. Use SUModelRemoveComponentDefinitions() to remove the image from a model.

Parameters

  [out] | image | The image object created.
  [in] | file_path | The file path of the source image file. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
  - SU_ERROR_OVERWRITE_VALID if image already references a valid object

enum SUResult SUImageCreateFromImageRep | ( | SUImageRef * | image,
|  | SUImageRepRef | image_rep
| ) |  |
| related

Creates a new SketchUp model image object from an image representation object. The created image must be subsequently added to the Entities of a model, component definition or a group. Use SUModelRemoveComponentDefinitions() to remove the image from a model.

Since
  SketchUp 2017, API 5.0

Parameters

  [out] | image | The image object created.
  [in] | image_rep | The basic image object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
  - SU_ERROR_OVERWRITE_VALID if image already references a valid object
  - SU_ERROR_INVALID_INPUT if image_rep is not a valid object
  - SU_ERROR_NO_DATA if the image_rep contains no data

SUImageRef SUImageFromDrawingElement | ( | SUDrawingElementRef | drawing_elem | ) |
| related

Converts from an SUDrawingElementRef to an SUImageRef. This is essentially a downcast operation so the given element must be convertible to an SUImageRef.

Parameters

  [in] | drawing_elem | The given element reference.

Returns
  - The converted SUImageRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

SUImageRef SUImageFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Parameters

  [in] | entity | The given entity reference.

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

enum SUResult SUImageGetData | ( | SUImageRef | image,
|  | size_t | data_size,
|  | SUByte | pixel_data[]
| ) |  |
| related

Returns the pixel data for an image. The given array must be large enough to hold the image's data. This size can be obtained by calling SUImageGetDataSize().

Deprecated:
  Will be removed in the next version of the SketchUp API. The functionality is replaced by SUImageGetImageRep followed by SUImageRepGetData.

Parameters

  [in] | image | The image object.
  [in] | data_size | The size of the byte array.
  [out] | pixel_data | The image data retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if pixel_data is NULL
  - SU_ERROR_INSUFFICIENT_SIZE if data_size is insufficient for the image data

enum SUResult SUImageGetDataSize | ( | SUImageRef | image,
|  | size_t * | data_size,
|  | size_t * | bits_per_pixel
| ) |  |
| related

Returns the total size and bits-per-pixel value of an image. This function is useful to determine the size of the buffer necessary to be passed into SUImageGetData(). The returned data can be used along with the returned bits-per-pixel value and the image dimensions to compute RGBA values at individual pixels of the image.

Deprecated:
  Will be removed in the next version of the SketchUp API. The functionality is replaced by SUImageGetImageRep followed by SUImageRepGetDataSize.

Parameters

  [in] | image | The image object.
  [out] | data_size | The total size of the image data in bytes.
  [out] | bits_per_pixel | The number of bits per pixel of the image data.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if data_size or bits_per_pixel is NULL

enum SUResult SUImageGetDefinition | ( | SUImageRef | image,
|  | SUComponentDefinitionRef * | component
| ) |  |
| related

Retrieves the component definition of an image object.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in] | image | The image object.
  [out] | component | The component definition retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `image` is not a valid object
  - SU_ERROR_OVERWRITE_VALID if `component` already refers to a valid object.
  - SU_ERROR_NULL_POINTER_OUTPUT if `component` is NULL

enum SUResult SUImageGetDimensions | ( | SUImageRef | image,
|  | double * | width,
|  | double * | height
| ) |  |
| related

Retrieves the world dimensions of an image object.

Parameters

  [in] | image | The image object.
  [out] | width | The width dimension retrieved.
  [out] | height | The height dimension retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if width or height is NULL

enum SUResult SUImageGetFileName | ( | SUImageRef | image,
|  | SUStringRef * | file_name
| ) |  |
| related

Retrieves the image file name of an image object.

Parameters

  [in] | image | The image object.
  [out] | file_name | The image file name retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if file_name is NULL
  - SU_ERROR_INVALID_OUTPUT if file_name does not point to a valid SUStringRef object

enum SUResult SUImageGetImageRep | ( | SUImageRef | image,
|  | SUImageRepRef * | image_rep
| ) |  |
| related

Retrieves a basic image from a SketchUp model image. The given image representation object must have been constructed using one of the SUImageRepCreate* functions. It must be released using SUImageRepRelease(). afterwards.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | image | The texture object.
  [out] | image_rep | The basic image object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if image_rep is NULL
  - SU_ERROR_INVALID_OUTPUT if image_rep does not point to a valid SUImageRepRef object
  - SU_ERROR_NO_DATA if there was no image data

enum SUResult SUImageGetName | ( | SUImageRef | image,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the name of an image object.

Parameters

  [in] | image | The image object.
  [out] | name | The name retrieved.

Deprecated:
  This function returns a property that should not exist. Use SUImageGetDefinition() and SUComponentDefinitionGetName() instead.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image 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 SUImageGetPixelDimensions | ( | SUImageRef | image,
|  | size_t * | width,
|  | size_t * | height
| ) |  |
| related

Retrieves the width and height dimensions of an image object in pixels.

Deprecated:
  Will be removed in the next version of the SketchUp API. The functionality is replaced by SUImageGetImageRep followed by SUImageRepGetPixelDimensions.

Parameters

  [in] | image | The image object.
  [out] | width | The width dimension retrieved.
  [out] | height | The height dimension retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if width or height is NULL

enum SUResult SUImageGetTransform | ( | SUImageRef | image,
|  | struct SUTransformation * | transform
| ) |  |
| related

Retrieves the 3-dimensional homogeneous transform of an image object.

Parameters

  [in] | image | The image object.
  [out] | transform | The transform retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

enum SUResult SUImageSetName | ( | SUImageRef | image,
|  | const char * | name
| ) |  |
| related

Sets the name of an image object.

Parameters

  [in,out] | image | The image object.
  [in] | name | The name to set. Assumed to be UTF-8 encoded.

Deprecated:
  This function sets a property that should not exist. Use SUImageGetDefinition() and SUComponentDefinitionSetName() instead.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL

enum SUResult SUImageSetTransform | ( | SUImageRef | image,
|  | const struct SUTransformation * | transform
| ) |  |
| related

Sets the 3-dimensional homogeneous transform of an image object.

Parameters

  [in,out] | image | The image object.
  [in] | transform | The affine transform to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if image is not a valid object or if the transform is not invertible
  - SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

SUDrawingElementRef SUImageToDrawingElement | ( | SUImageRef | image | ) |
| related

Converts from an SUImageRef to an SUDrawingElementRef. This is essentially an upcast operation.

Parameters

  [in] | image | The given image reference.

Returns
  - The converted SUEntityRef if image is a valid image
  - If not, the returned reference will be invalid

SUEntityRef SUImageToEntity | ( | SUImageRef | image | ) |
| related

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

Parameters

  [in] | image | The given image reference.

Returns
  - The converted SUEntityRef if image is a valid image.
  - If not, the returned reference will be invalid.

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

- SketchUpAPI/model/defs.h
- SketchUpAPI/model/image.h