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

#include <SketchUpAPI/model/texture.h>

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
	)

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[]
	)

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
	)

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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[]
	)

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
	)

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
	)

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
	)

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 )

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
	)

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
	)

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 )

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
	)

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
	)

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

Related Functions

Detailed Description

Friends And Related Function Documentation