LayOut C API

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Functions
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 | LOImageGetOutputImageRep (LOImageRef image, LOImageRepRef *imagerep)
| Gets an image object's image representation in the document's output resolution. More...
LO_RESULT | LOImageGetClipMask (LOImageRef image, LOEntityRef *clip_mask)
| Returns any clip mask assigned to the image. More...
LO_RESULT | LOImageSetClipMask (LOImageRef image, 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 LOImageGetOutputImageRep | ( | LOImageRef | image,
|  | LOImageRepRef * | imagerep
| ) |  |

Gets an image object's image representation in the document's output resolution.

This should be used by exporters to retrieve the image data at the quality set by LOPageInfoSetImageOutputResolution.

Since
  LayOut 2023.1, API 8.1

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 | image,
|  | 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] | image | 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