cl-libheif ยป API

Conditions

cl-libheif-error
Generic cl-libheif error
    libheif-error
    Libheif error. It's signalled when libheif returns an error code.
    • message
      Allocationinstance
      Typestring
      Initarg:message
      Readers(error-message)
    • code
      Allocationinstance
      Type(integer 0)
      Initarg:code
      Readers(error-code)
    • subcode
      Allocationinstance
      Type(integer 0)
      Initarg:subcode
      Readers(error-subcode)
    bps-error
    Signalled by the wrapper when libheif reports a BPS value which is unsupported by this wrapper.
    • bps
      Allocationinstance
      Typeinteger
      Initarg:bps
      Readers(error-bps)
    no-plane-error
    Signalled by the wrapper when there is no requested plane in the image.
      dimensions-mismatch
      Signalled when trying to set data of the wrong dimensionality to a plane.
      • dims
        Allocationinstance
        Typenil
        Initarg:dims
        Readers(mismatched-dims)

      libheif (de)initialization

      +default-init-parameters+
      Default libheif init parameters.
      with-libheif((parameters) &body body)
      Initialize libheif and execute body. Libheif is deinitialized when the control leaves body.

      Context

      with-context((context) &body body)
      Bind context to a newly created libheif context and execute body in its scope. The context is destroyed when the control leaves body.
      with-stream-reader((reader stream) &body body)
      Bind reader to a newly created stream reader which is used in context-read-from-stream!. All image reading and decoding must be performed within body if you read an image from a stream. Stream is an actual stream from which the image is read. It must have the element type (unsigned-byte 8).
      context-read-from-file!(context filename)
      Read an image from a file.
      context-read-from-octets!(context array)
      Read an image from a simple array of octets (of type (unsigned-byte 8)).
      context-read-from-stream!(context reader)
      Read an image from a stream. The reader is created with with-stream-reader and all image reading and decoding (not only a call to this function) must be done in the body of that macro. Currently, this function also disables multithreaded decoding, but you can always create as many lisp threads (with their own libheif contexts) as you wish.
      context-write-to-file!(context filename)
      Write context to a file.
      context-write-to-stream!(context stream)
      Write context to a binary stream (element type must be (unsigned-byte 8)).
      context-write-to-octets(context)
      Write context to a simple array of octets.
      context-top-level-image-ids(context &optional (max-ids 0))
      Return a list of toplevel image ids. If max-ids > 0, return no more than max-ids.
      context-primary-image-id(context)
      Get ID of a primary toplevel image.
      context-set-maximum-image-size-limit!(context width)
      Set the maximum image size security limit. This function will set the maximum image area (number of pixels) to (expt width 2).
      context-set-max-decoding-threads!(context nthreads)
      Set the maximal number of threads used by libheif. Setting this to 0 means decoding in the main thread, while 1 means that a separate thread dedicated to decoding is created.

      Image handles

      with-primary-image-handle((handle context) &body body)
      Bind handle to the primary image handle in the context and execute body in the scope of that handle. This macro ensures that the handle is released when the control leaves body.
      with-image-handle((handle context id) &body body)
      Bind handle to an image handle with specified id and execute body in its scope. Make sure the handle is released when the control leaves body.
      image-handle-width(handle)
      Get width of the image
      image-handle-height(handle)
      Get height of the image
      colorspace(nil (quote (member :undefined :ycbcr :rgb :monochrome :nonvisual)))
      A type for the colorspace of an image.
      chroma(nil (quote (member :undefined :monochrome :|420| :|422| :|444| :interleaved-rgb :interleaved-rgba :interleaved-rrggbb-be :interleaved-rrggbbaa-be :interleaved-rrggbb-le :interleaved-rrggbbaa-le)))
      A type which represents how color is encoded in the image.
      image-handle-preferred-decoding-colorspace(handle)
      Get the colorspace and chroma parameters which are preferred when decoding the image.

      Images

      channel(nil (quote (member :y :cb :cr :r :g :b :alpha :interleaved :filter-array :depth :disparity)))
      A type which represents a channel in the image.
      image-width(image channel)
      Get width of a channel in the image.
      image-height(image channel)
      Get height of a channel in the image.
      image-bits-per-pixel(image channel)
      Get the number of bits per pixel in the given image channel. Returns -1 if a non-existing channel was given. Note that the number of bits per pixel may be different for each color channel. This function returns the number of bits used for storage of each pixel. Especially for HDR images, this is probably not what you want. Have a look at image-bits-per-pixel-range.
      image-bits-per-pixel-range(image channel)

      Get the number of bits per pixel in the given image channel. This function returns the number of bits used for representing the pixel value, which might be smaller than the number of bits used in memory.

      For example, in 12bit HDR images, this function returns '12', while still 16 bits are reserved for storage. For interleaved RGBA with 12 bit, this function also returns '12', not '48' or '64' (image-bits-per-pixel returns 64 in this case).

      image-plane-data(image channel)
      Get a simple array of octets which contains plane data. In the case of monochrome channels (:monochrome, :r, :y etc.) the returned array has dimensions (height width 1). In the case of interleaved color channels the returned array has dimensions (height width 3) or (height weight 4)(the latter with alpha channel).
      image-has-plane-p(image channel)
      Return t if an image has a plane specified by channel, nil otherwise.
      with-image((image width height colorspace chroma) &body body)
      Bind image to a new image and execute body in its scope. Make sure the image is released when the control leaves body.
      image-add-plane!(image channel width height bit-depth)
      Add a plane to an image. The actual data must be transferred to the plane via image-set-plane-data!.
      image-set-plane-data!(image channel data)
      Copy a simple array of octets to a plane which is previously created with image-add-plane!. The array must have dimensions (height width 1) for monochrome/one color per channel data or (height width 3) / (height width 4) for interleaved color data (the latter with alpha).

      Encoding

      encoder-descriptors(&optional (format-filter :undefined) name-filter)
      Get a list of encoder descriptors supported by libheif.
      encoder-descriptor-name(descriptor)
      Return a long, descriptive name of the encoder (including version information).
      encoder-descriptor-id-name(descriptor)
      Return a short, symbolic name for identifying the encoder. This name should stay constant over different encoder versions.
      encoder-descriptor-compression-format(descriptor)
      Get compression format for this encoder.
      encoder-descriptor-supports-lossy-compression-p(descriptor)
      Return t if this encoder supports lossy compression, nil oterwise.
      encoder-descriptor-supports-lossless-compression-p(descriptor)
      Return t if this encoder supports lossless compression, nil oterwise.
      +default-encoding-options+
      Default encoding options
      compression-format(nil (quote (member :undefined :hevc :avc :jpeg :av1 :vvc :evc :jpeg2000 :uncompressed :mask :htj2k)))
      A type which represents a compression format and is used in encoder selection.
      with-encoder((encoder context descriptor) &body body)
      Bind encoder to a reference to the encoder by its descriptor and execute body in its scope. Make sure it is released when the control leaves body.
      with-encoder-for-format((encoder context format) &body body)
      Bind encoder to an encoder for the specified format and execute body in its scope. Ensure that the encoder is released when the control leaves body.
      encoder-set-lossy-quality!(encoder quality)
      Set a 'quality' factor (0-100). How this is mapped to actual encoding parameters is encoder dependent.
      encoder-set-lossless!(encoder enablep)
      Enable or disable lossless encoding.
      context-encode-image!(context image encoder options)
      Compress the input image. The first compressed image becomes the primary image in that context.

      Decoding

      +default-decoding-options+
      Default decoding options
      with-decode-image((image handle colorspace chroma options) &body body)
      Bind image to a decoded image and execute body in the scope of that image. Make sure the image is released when the control leaves body.

      Metadata

      metadata-ref
      • size
        Type(unsigned-byte 64)
        Readercl-libheif:metadata-ref-size
      • id
        Type(unsigned-byte 32)
        Readercl-libheif:metadata-ref-id
      image-handle-metadata-refs(handle &optional filter (max-ids 0))
      Get a list of metadata blocks. If MAX-IDS is positive, return no more than MAX-IDS entries.
      image-handle-metadata(handle ref)
      Get a metadata block by its reference.