image.h File Reference

#include <LayOutAPI/common.h>
#include <LayOutAPI/geometry/geometry.h>
#include <LayOutAPI/model/defs.h>

Go to the source code of this file.

Functions
LO_RESULT	LOImageCreateFromFile (LOImageRef *image, const LOAxisAlignedRect2D *bounds, const char *file_path)
	Creates a new image object from an image file on disk. More...
LO_RESULT	LOImageAddReference (LOImageRef image)
	Adds a reference to an image object. More...
LO_RESULT	LOImageRelease (LOImageRef *image)
	Releases an image object. The object will be invalidated if releasing the last reference. More...
LO_EXPORT LOImageRef	LOImageFromEntity (LOEntityRef entity)
	Converts from a LOEntityRef to a LOImageRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOImageRef. More...
LO_EXPORT LOEntityRef	LOImageToEntity (LOImageRef image)
	Converts from a LOImageRef to a LOEntityRef. This is essentially an upcast operation. More...
LO_RESULT	LOImageGetImageRep (LOImageRef image, LOImageRepRef *imagerep)
	Gets an image object's image representation. More...
LO_RESULT	LOImageGetClipMask (LOImageRef image, LOEntityRef *clip_mask)
	Returns any clip mask assigned to the image. More...
LO_RESULT	LOImageSetClipMask (LOImageRef model, LOEntityRef clip_mask)
	Sets the clip mask of the image. A clip mask defines a region of the entity that is visible. This allows you to crop with arbitrary shapes. This operation will replace any clip mask that is already assigned to this image. The entity being used must not be already part of a document or group. The clip mask entity must be either a rectangle, ellipse or a path. More...

Function Documentation

LO_RESULT LOImageAddReference

(

LOImageRef

image

)

Adds a reference to an image object.

Parameters

[in]

image

The image object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if image does not refer to a valid object

LO_RESULT LOImageCreateFromFile	(	LOImageRef *	image,
		const LOAxisAlignedRect2D *	bounds,
		const char *	file_path
	)

Creates a new image object from an image file on disk.

Parameters

[out]	image	The image object.
[in]	bounds	The bounding box for the image.
[in]	file_path	The file path to the image on disk.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
• SU_ERROR_OVERWRITE_VALID if *image already refers to a valid object
• SU_ERROR_NULL_POINTER_INPUT if bounds is NULL
• SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
• SU_ERROR_OUT_OF_RANGE if bounds has a width or height of zero
• SU_ERROR_SERIALIZATION if there was an error reading the image file or allocating the memory for the image
• SU_ERROR_NO_DATA if the image file could not be found

LO_EXPORT LOImageRef LOImageFromEntity

(

LOEntityRef

entity

)

Converts from a LOEntityRef to a LOImageRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOImageRef.

Parameters

[in]

entity

The entity object.

Returns

• The converted LOImageRef if the downcast operation succeeds
• If not, the returned reference will be invalid

LO_RESULT LOImageGetClipMask	(	LOImageRef	image,
		LOEntityRef *	clip_mask
	)

Returns any clip mask assigned to the image.

Parameters

[in]	image	The image object.
[out]	clip_mask	The clip mask of the image.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if image does not refer to a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if clip_mask is NULL
• SU_ERROR_OVERWRITE_VALID if *clip_mask already refers to a valid object
• SU_ERROR_NO_DATA if the image is not being clipped by a clip mask

LO_RESULT LOImageGetImageRep	(	LOImageRef	image,
		LOImageRepRef *	imagerep
	)

Gets an image object's image representation.

Parameters

[in]	image	The image object.
[out]	imagerep	The image representation object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if image does not refer to a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if imagerep is NULL
• SU_ERROR_OVERWRITE_VALID if *imagerep already refers to a valid object

LO_RESULT LOImageRelease

(

LOImageRef *

image

)

Releases an image object. The object will be invalidated if releasing the last reference.

Parameters

[in]

image

The image object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if image is NULL
• SU_ERROR_INVALID_INPUT if *image does not refer to a valid object

LO_RESULT LOImageSetClipMask	(	LOImageRef	model,
		LOEntityRef	clip_mask
	)

Sets the clip mask of the image. A clip mask defines a region of the entity that is visible. This allows you to crop with arbitrary shapes. This operation will replace any clip mask that is already assigned to this image. The entity being used must not be already part of a document or group. The clip mask entity must be either a rectangle, ellipse or a path.

Note

Starting in LayOut 2020.1, API 5.1, clip_mask may be SU_INVALID, which will remove the existing clip mask, if any.

Since

LayOut 2017, API 2.0

Parameters

[in]	model	The image object.
[in]	clip_mask	The new clip mask for the image.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if image does not refer to a valid object
• SU_ERROR_INVALID_ARGUMENT if clip_mask is already in a document or group
• SU_ERROR_UNSUPPORTED if clip_mask is not a rectangle, ellipse, or path
• SU_ERROR_LAYER_LOCKED if image is on a locked layer
• SU_ERROR_ENTITY_LOCKED if image is locked

LO_EXPORT LOEntityRef LOImageToEntity

(

LOImageRef

image

)

Converts from a LOImageRef to a LOEntityRef. This is essentially an upcast operation.

Parameters

[in]

image

The image object.

Returns

• The converted LOEntityRef if image is a valid object
• If not, the returned reference will be invalid