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

Functions
LO_RESULT	LOReferenceEntityAddReference (LOReferenceEntityRef reference_entity)
	Adds a reference to a reference entity object. More...

LO_RESULT	LOReferenceEntityRelease (LOReferenceEntityRef *reference_entity)
	Releases a reference entity object. The object will be invalidated if releasing the last reference. More...

LO_EXPORT LOReferenceEntityRef	LOReferenceEntityFromEntity (LOEntityRef entity)
	Converts from a LOEntityRef to a LOReferenceEntityRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOReferenceEntityRef. More...

LO_EXPORT LOEntityRef	LOReferenceEntityToEntity (LOReferenceEntityRef reference_entity)
	Converts from a LOReferenceEntityRef to a LOEntityRef. This is essentially an upcast operation. More...

LO_RESULT	LOReferenceEntityGetClipMask (LOReferenceEntityRef reference_entity, LOEntityRef *clip_mask)
	Returns any clip mask assigned to the reference entity. More...

LO_RESULT	LOReferenceEntitySetClipMask (LOReferenceEntityRef reference_entity, LOEntityRef clip_mask)
	Sets the clip mask of the reference entity. More...

LO_RESULT	LOReferenceEntityGetExplodedEntities (LOReferenceEntityRef reference_entity, LOEntityListRef entity_list)
	Creates the entities that represent the reference entity in its exploded form and adds them to a LOEntityListRef. It is NOT necessary to explicitly release these entities, since LOEntityListRef itself adds a reference to the entities and will release them when they are removed from the list or when the list is released. More...

Function Documentation

LO_RESULT LOReferenceEntityAddReference ( LOReferenceEntityRef reference_entity )

Adds a reference to a reference entity object.

Since: LayOut 2023, API 8.0

Parameters

[in] reference_entity The reference entity object.

Returns

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

LO_EXPORT LOReferenceEntityRef LOReferenceEntityFromEntity ( LOEntityRef entity )

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

Since: LayOut 2023, API 8.0

Parameters

[in] entity The entity object.

Returns

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

LO_RESULT LOReferenceEntityGetClipMask	(	LOReferenceEntityRef	reference_entity,
		LOEntityRef *	clip_mask
	)

Returns any clip mask assigned to the reference entity.

Since: LayOut 2023, API 8.0

Parameters

[in]	reference_entity	The reference entity object.
[out]	clip_mask	The clip mask of the reference entity.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if reference_entity 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 reference entity is not being clipped by a clip mask

LO_RESULT LOReferenceEntityGetExplodedEntities	(	LOReferenceEntityRef	reference_entity,
		LOEntityListRef	entity_list
	)

Creates the entities that represent the reference entity in its exploded form and adds them to a LOEntityListRef. It is NOT necessary to explicitly release these entities, since LOEntityListRef itself adds a reference to the entities and will release them when they are removed from the list or when the list is released.

Since: LayOut 2023, API 8.0

Parameters

[in]	reference_entity	The reference entity object.
[in]	entity_list	The entity list object to add the new entities to.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if reference_entity does not refer to a valid object
SU_ERROR_INVALID_INPUT if entity_list does not refer to a valid object

LO_RESULT LOReferenceEntityRelease ( LOReferenceEntityRef * reference_entity )

Releases a reference entity object. The object will be invalidated if releasing the last reference.

Since: LayOut 2023, API 8.0

Parameters

[in] reference_entity The reference entity object.

Returns

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

LO_RESULT LOReferenceEntitySetClipMask	(	LOReferenceEntityRef	reference_entity,
		LOEntityRef	clip_mask
	)

Sets the clip mask of the reference entity.

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 reference entity. The entity being used must not already be part of a document or group. The clip mask entity must be either a rectangle, ellipse or a path, or may be SU_INVALID, which will remove the existing clip mask, if any.

Note: Starting in LayOut 2026.2, API 11.2, clip_mask bounds must overlap reference_entity bounds.

Since: LayOut 2023, API 8.0

Parameters

[in]	reference_entity	The reference entity object.
[in]	clip_mask	The new clip mask for the reference entity.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if reference_entity does not refer to a valid object
SU_ERROR_GENERIC if clip_mask is already in a document or group
SU_ERROR_UNSUPPORTED if clip_mask is not a LORectangleRef, LOEllipseRef, or LOPathRef, or if reference_entity and clip_mask bounds do not overlap
SU_ERROR_LAYER_LOCKED if reference_entity is on a locked layer
SU_ERROR_ENTITY_LOCKED if reference_entity is locked

LO_EXPORT LOEntityRef LOReferenceEntityToEntity ( LOReferenceEntityRef reference_entity )

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

Since: LayOut 2023, API 8.0

Parameters

[in] reference_entity The reference entity object.

Returns

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

Functions

Function Documentation