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

Used to manage image data that can be associated with any SUEntityRef. More...

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

Inherits SUEntityRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUTextureToEntity (SUTextureRef texture)
| Converts from an SUTextureRef to an SUEntityRef. This is essentially an upcast operation. More...
SUTextureRef | SUTextureFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUTextureRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUTextureRef. More...
enum SUResult | SUTextureCreateFromImageData (SUTextureRef *texture, size_t width, size_t height, size_t bits_per_pixel, const SUByte pixel_data[])
| Creates a new texture object with the specified image data. If the texture object is not subsequently associated with a parent object (e.g. material), then the texture object must be deallocated with SUTextureRelease. More...
enum SUResult | SUTextureCreateFromImageRep (SUTextureRef *texture, SUImageRepRef image)
| Creates a new texture object from an image representation object. More...
enum SUResult | SUTextureCreateFromFile (SUTextureRef *texture, const char *file_path, double s_scale, double t_scale)
| Creates a new texture object from an image file specified by a path. If the texture object is not subsequently associated with a parent object (e.g. material), then the texture object must be deallocated with SUTextureRelease. More...
enum SUResult | SUTextureRelease (SUTextureRef *texture)
| Deallocates a texture object and its resources. If the texture object is associated with a parent object (e.g. material) the parent object handles the deallocation of the resources of the texture object and the texture object must not be explicitly deallocated. More...
enum SUResult | SUTextureGetDimensions (SUTextureRef texture, size_t *width, size_t *height, double *s_scale, double *t_scale)
| Retrieves the pixel width, height, and scale factors of the texture. More...
enum SUResult | SUTextureSetDimensions (SUTextureRef texture, double s_scale, double t_scale)
| Sets the scale factors of the texture. More...
enum SUResult | SUTextureGetImageDataSize (SUTextureRef texture, size_t *data_size, size_t *bits_per_pixel)
| Returns the total size and bits-per-pixel value of a texture's image data. This function is useful to determine the size of the buffer necessary to be passed into SUTextureGetImageData(). The returned data can be used along with the returned bits-per-pixel value and the texture dimensions to compute RGBA values at individual pixels of the texture image. More...
enum SUResult | SUTextureGetImageData (SUTextureRef texture, size_t data_size, SUByte pixel_data[])
| Returns the texture's image data. The given array must be large enough to hold the texture's image data. This size can be obtained by calling SUTextureGetImageDataSize(). More...
enum SUResult | SUTextureGetImageRep (SUTextureRef texture, SUImageRepRef *image)
| Retrieves a texture's image. The given image object must have been constructed using one of the SUImageRepCreate* functions. It must be released using SUImageRepRelease(). The difference between this function and SUTextureGetColorizedImageRep() is that SUTextureGetColorizedImageRep() will retrieve the colorized image rep, if the material has been colorized. More...
enum SUResult | SUTextureWriteToFile (SUTextureRef texture, const char *file_path)
| Writes a texture object as an image to disk. If the material has been colorized this will write out a colorized texture. Use SUTextureWriteOriginalToFile() to obtain the original texture without colorization. More...
enum SUResult | SUTextureSetFileName (SUTextureRef texture, const char *name)
| Sets the image file name string associated with the texture object. If the input texture was constructed using SUTextureCreateFromFile the name will already be set, so calling this function will override the texture's file name string. More...
enum SUResult | SUTextureGetFileName (SUTextureRef texture, SUStringRef *file_name)
| Retrieves the image file basename of a texture object. A full path may be stored with the texture, but this method will always return a file name string with no path. If the texture was created from an SUImageRepRef created with SUImageRepLoadFile() then this will return only the file extension representing the file format of the image data (e.g. ".png"). More...
enum SUResult | SUTextureGetFilePath (SUTextureRef texture, SUStringRef *file_path)
| Retrieves the image file path of a texture object. More...
enum SUResult | SUTextureGetUseAlphaChannel (SUTextureRef texture, bool *alpha_channel_used)
| Retrieves the value of the flag that indicates whether a texture object uses the alpha channel. More...
enum SUResult | SUTextureGetAverageColor (SUTextureRef texture, SUColor *color_val)
| Retrieves the average color for the texture. More...
enum SUResult | SUTextureGetColorizedImageRep (SUTextureRef texture, SUImageRepRef *image_rep)
| Retrieves the image rep object of a colorized texture. If a non-colorized texture is used, then the original image rep will be retrieved. The difference between this function and SUTextureGetImageRep is that SUTextureGetImageRep() will always retrieve the original image rep. More...
enum SUResult | SUTextureWriteOriginalToFile (SUTextureRef texture, const char *file_path)
| Writes a texture object as an image to disk without any colorization. If the texture was created from a file on disk this will write out the original file data if the provided file extension matches. This will be the fastest way to extract the original texture from the model. Use SUTextureGetFilename() to obtain the original file format. 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 manage image data that can be associated with any SUEntityRef.

## Friends And Related Function Documentation

enum SUResult SUTextureCreateFromFile | ( | SUTextureRef * | texture,
|  | const char * | file_path,
|  | double | s_scale,
|  | double | t_scale
| ) |  |
| related

Creates a new texture object from an image file specified by a path. If the texture object is not subsequently associated with a parent object (e.g. material), then the texture object must be deallocated with SUTextureRelease.

Parameters

  [out] | texture | The texture object created.
  [in] | file_path | The file path of the source image file. Assumed to be UTF-8 encoded.
  [in] | s_scale | The scale factor for s coordinate value.
  [in] | t_scale | The scale factor for t coordinate value.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
  - SU_ERROR_SERIALIZATION if the image file could not be opened
  - SU_ERROR_GENERIC if a texture could not be created from the image file
  - SU_ERROR_NULL_POINTER_OUTPUT if texture is NULL
  - SU_ERROR_OVERWRITE_VALID is texture already references a valid object

enum SUResult SUTextureCreateFromImageData | ( | SUTextureRef * | texture,
|  | size_t | width,
|  | size_t | height,
|  | size_t | bits_per_pixel,
|  | const SUByte | pixel_data[]
| ) |  |
| related

Creates a new texture object with the specified image data. If the texture object is not subsequently associated with a parent object (e.g. material), then the texture object must be deallocated with SUTextureRelease.

Deprecated:
  Will be removed in the next version of the SketchUp API. The functionality is replaced by SUImageRepSetData() followed by SUTextureCreateFromImageRep().

Parameters

  [out] | texture | The texture object created.
  [in] | width | The width in pixels of the texture data.
  [in] | height | The height in pixels of the texture data.
  [in] | bits_per_pixel | The number of bits per pixel of the image data.
  [in] | pixel_data | The source of the pixel data.

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

enum SUResult SUTextureCreateFromImageRep | ( | SUTextureRef * | texture,
|  | SUImageRepRef | image
| ) |  |
| related

Creates a new texture object from an image representation object.

Since
  SketchUp 2017, API 5.0

Parameters

  [out] | texture | The texture object created.
  [in] | image | The image retrieved.

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

SUTextureRef SUTextureFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Parameters

  [in] | entity | The entity reference.

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

enum SUResult SUTextureGetAverageColor | ( | SUTextureRef | texture,
|  | SUColor * | color_val
| ) |  |
| related

Retrieves the average color for the texture.

Parameters

  [in] | texture | The texture object
  [out] | color_val | The color object

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if color_val is NULL

enum SUResult SUTextureGetColorizedImageRep | ( | SUTextureRef | texture,
|  | SUImageRepRef * | image_rep
| ) |  |
| related

Retrieves the image rep object of a colorized texture. If a non-colorized texture is used, then the original image rep will be retrieved. The difference between this function and SUTextureGetImageRep is that SUTextureGetImageRep() will always retrieve the original image rep.

Since
  SketchUp 2018, API 6.0

Parameters

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

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if image_rep is NULL
  - SU_ERROR_NO_DATA if no data was retrieved from the texture
  - SU_ERROR_OUT_OF_RANGE if the pixel data is out of range

enum SUResult SUTextureGetDimensions | ( | SUTextureRef | texture,
|  | size_t * | width,
|  | size_t * | height,
|  | double * | s_scale,
|  | double * | t_scale
| ) |  |
| related

Retrieves the pixel width, height, and scale factors of the texture.

Note
  The s_scale and t_scale values are useful when a face doesn't have a material applied directly, but instead inherit from a parent group or component instance. Then you want use these values to multiply the result of SUMeshHelperGetFrontSTQCoords() or SUUVHelperGetFrontUVQ(). If the material is applied directly then this would not be needed.
  For PBR textures (metallic, roughness, normal, and ambient occlusion) the s_scale and t_scale values are only used when the PBR material doesn't have a base texture.

Parameters

  [in] | texture | The texture object whose dimensions are retrieved.
  [out] | width | The width in pixels.
  [out] | height | The height in pixels.
  [out] | s_scale | The s coordinate scale factor to map a pixel into model coordinates.
  [out] | t_scale | The t coordinate scale factor to map a pixel into model coordinates.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if width, height, s_scale, or t_scale is NULL

enum SUResult SUTextureGetFileName | ( | SUTextureRef | texture,
|  | SUStringRef * | file_name
| ) |  |
| related

Retrieves the image file basename of a texture object. A full path may be stored with the texture, but this method will always return a file name string with no path. If the texture was created from an SUImageRepRef created with SUImageRepLoadFile() then this will return only the file extension representing the file format of the image data (e.g. ".png").

Parameters

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

See Also
  SUTextureGetFilePath

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is not a valid object
  - SU_ERROR_GENERIC if the texture is an unknown file type
  - 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 SUTextureGetFilePath | ( | SUTextureRef | texture,
|  | SUStringRef * | file_path
| ) |  |
| related

Retrieves the image file path of a texture object.

If the texture was created from an SUImageRepRef created with SUImageRepLoadFile() then this will return only the file extension representing the file format of the image data (e.g. ".png").

Parameters

  [in] | texture | The texture object.
  [out] | file_path | The file path retrieved.

Since
  SketchUp 2023.1, API 11.1

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `texture` is not a valid object
  - SU_ERROR_GENERIC if the `texture` is an unknown file type
  - SU_ERROR_NULL_POINTER_OUTPUT if `file_path` is NULL
  - SU_ERROR_INVALID_OUTPUT if `file_path` does not point to a valid SUStringRef object

enum SUResult SUTextureGetImageData | ( | SUTextureRef | texture,
|  | size_t | data_size,
|  | SUByte | pixel_data[]
| ) |  |
| related

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

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

Parameters

  [in] | texture | The texture 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 texture 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 SUTextureGetImageDataSize | ( | SUTextureRef | texture,
|  | size_t * | data_size,
|  | size_t * | bits_per_pixel
| ) |  |
| related

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

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

Parameters

  [in] | texture | The texture 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 texture is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if data_size or bits_per_pixel is NULL

enum SUResult SUTextureGetImageRep | ( | SUTextureRef | texture,
|  | SUImageRepRef * | image
| ) |  |
| related

Retrieves a texture's image. The given image object must have been constructed using one of the SUImageRepCreate* functions. It must be released using SUImageRepRelease(). The difference between this function and SUTextureGetColorizedImageRep() is that SUTextureGetColorizedImageRep() will retrieve the colorized image rep, if the material has been colorized.

Since
  SketchUp 2017, API 5.0

Parameters

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

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture 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 no image was created

enum SUResult SUTextureGetUseAlphaChannel | ( | SUTextureRef | texture,
|  | bool * | alpha_channel_used
| ) |  |
| related

Retrieves the value of the flag that indicates whether a texture object uses the alpha channel.

Parameters

  [in] | texture | The texture object.
  [out] | alpha_channel_used | The destination of the retrieved value.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if alpha_channel_used is NULL
  - SU_ERROR_NO_DATA if the flag value could not be retrieved

enum SUResult SUTextureRelease | ( | SUTextureRef * | texture | ) |
| related

Deallocates a texture object and its resources. If the texture object is associated with a parent object (e.g. material) the parent object handles the deallocation of the resources of the texture object and the texture object must not be explicitly deallocated.

Parameters

  [in] | texture | The texture object to deallocate.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if texture is NULL
  - SU_ERROR_INVALID_INPUT if texture does not refer to a valid object

enum SUResult SUTextureSetDimensions | ( | SUTextureRef | texture,
|  | double | s_scale,
|  | double | t_scale
| ) |  |
| related

Sets the scale factors of the texture.

Note
  For PBR textures (metallic, roughness, normal, and ambient occlusion) the `s_scale` and `t_scale` values are only used when the PBR material doesn't have a base texture.

Since
  SketchUp 2025.0, API 13.0

Parameters

  texture | The texture object whose dimensions are set.
  s_scale | The s coordinate scale factor to map a pixel into model coordinates.
  t_scale | The t coordinate scale factor to map a pixel into model coordinates.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `texture` is an invalid object
  - SU_ERROR_OUT_OF_RANGE if `s_scale`, or `t_scale` is smaller or equal to 0

enum SUResult SUTextureSetFileName | ( | SUTextureRef | texture,
|  | const char * | name
| ) |  |
| related

Sets the image file name string associated with the texture object. If the input texture was constructed using SUTextureCreateFromFile the name will already be set, so calling this function will override the texture's file name string.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | texture | The texture object.
  [in] | name | The name string to set as the file name. Assumed to be UTF-8 encoded.

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

SUEntityRef SUTextureToEntity | ( | SUTextureRef | texture | ) |
| related

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

Parameters

  [in] | texture | The texture reference.

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

enum SUResult SUTextureWriteOriginalToFile | ( | SUTextureRef | texture,
|  | const char * | file_path
| ) |  |
| related

Writes a texture object as an image to disk without any colorization. If the texture was created from a file on disk this will write out the original file data if the provided file extension matches. This will be the fastest way to extract the original texture from the model. Use SUTextureGetFilename() to obtain the original file format.

Since
  SketchUp 2019.2, API 7.1

Parameters

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

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
  - SU_ERROR_SERIALIZATION if image file could not be written to disk

enum SUResult SUTextureWriteToFile | ( | SUTextureRef | texture,
|  | const char * | file_path
| ) |  |
| related

Writes a texture object as an image to disk. If the material has been colorized this will write out a colorized texture. Use SUTextureWriteOriginalToFile() to obtain the original texture without colorization.

Parameters

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

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if texture is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
  - SU_ERROR_SERIALIZATION if image file could not be written to disk

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

- SketchUpAPI/model/defs.h
- SketchUpAPI/model/texture.h