SketchUp C API
 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. 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. 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...
 

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]textureThe texture object created.
[in]file_pathThe file path of the source image file. Assumed to be UTF-8 encoded.
[in]s_scaleThe scale factor for s coordinate value.
[in]t_scaleThe scale factor for t coordinate value.
Returns
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]textureThe texture object created.
[in]widthThe width in pixels of the texture data.
[in]heightThe height in pixels of the texture data.
[in]bits_per_pixelThe number of bits per pixel of the image data.
[in]pixel_dataThe source of the pixel data.
Returns
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]textureThe texture object created.
[in]imageThe image retrieved.
Returns
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]entityThe 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]textureThe texture object
[out]color_valThe color object
Returns
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]textureThe texture object.
[out]image_repThe retrieved image rep.
Returns
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. 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.

Parameters
[in]textureThe texture object whose dimensions are retrieved.
[out]widthThe width in pixels.
[out]heightThe height in pixels.
[out]s_scaleThe s coordinate scale factor to map a pixel into model coordinates.
[out]t_scaleThe t coordinate scale factor to map a pixel into model coordinates.
Returns
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]textureThe texture object.
[out]file_nameThe file name retrieved.
See Also
SUTextureGetFilePath
Returns
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]textureThe texture object.
[out]file_pathThe file path retrieved.
Since
SketchUp 2023.1, API 11.1
Returns
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]textureThe texture object.
[in]data_sizeThe size of the byte array.
[out]pixel_dataThe image data retrieved.
Returns
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]textureThe texture object.
[out]data_sizeThe total size of the image data in bytes.
[out]bits_per_pixelThe number of bits per pixel of the image data.
Returns
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]textureThe texture object.
[out]imageThe image object retrieved.
Returns
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]textureThe texture object.
[out]alpha_channel_usedThe destination of the retrieved value.
Returns
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]textureThe texture object to deallocate.
Returns
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]textureThe texture object.
[in]nameThe name string to set as the file name. Assumed to be UTF-8 encoded.
Returns
SUEntityRef SUTextureToEntity ( SUTextureRef  texture)
related

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

Parameters
[in]textureThe 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]textureThe texture object.
[in]file_pathThe file path destination of the texture image. Assumed to be UTF-8 encoded.
Returns
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]textureThe texture object.
[in]file_pathThe file path destination of the texture image. Assumed to be UTF-8 encoded.
Returns

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