References an image object. More...

#include <SketchUpAPI/model/image.h>

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
	)

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
	)

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 )

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 )

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

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

Parameters

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

Parameters

[in]	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
SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

SUDrawingElementRef SUImageToDrawingElement ( SUImageRef image )

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 )

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

Related Functions

Detailed Description

Friends And Related Function Documentation