jpeg-turbo ยป API

To compress an image you need to create a compressor object using with-compressor macro and then call compress-to-octets function supplying an array of pixels you want to become a jpeg image. The result is an array of octets representing the compressed image. You can write the result directly to file using compress instead. This example creates an image with dimensions 200x300 filled with red color: 

(let* ((width 200)
       (height 300)
       (array (make-array (* 3 width height)
                          :element-type '(unsigned-byte 8))))
     (loop for i below (length array) by 3 do
         (setf (aref array i) 255))
     (jpeg-turbo:with-compressor (handle)
       (jpeg-turbo:compress handle "~/test.jpg" array width height :rgb)))

with-compressor((handle) &body body)
Execute the macro's body in the lexical scope of created compressor handle handle. The handle is safely freed after use.
compress-to-octets(handle array width height pixel-format &key (quality 90) (subsamp s-444) flags)
Compress an image to jpeg format. handle is a compressor handle created with with-compressor. array is a simple array of (unsigned-byte 8) values containing pixel data. Values of pixel-format described in section pixel formats. quality is an integer from 1 to 100. Higher values mean better quality. subsamp is described in subsampling section and flags in flags section.
compress(handle filename array width height pixel-format &key (quality 90) (subsamp s-444) flags)
Compress an image to jpeg format and write it to file with the name filename. See compress-to-octets for more info.

Decompression is handled in the similar way: you create a decompressor object using :with-decompressor and use a function decompress-from-octets(when you decompress from array of octets) or decompress(when you decompress from file). Also you can decompress the header of an image only (see below).

with-decompressor((handle) &body body)
Execute the macro's body in the lexical scope of created decompressor handle handle. The handle is safely freed after use.
scaling-factorsnil
Return scaling factors supported by libjpeg-turbo
decompress-from-octets(handle array &key (scaling-factor 1) (pixel-format rgb) flags)

Decompress a jpeg image. handle is a decompressor handle created with with-decompressor. array is a simple array of (unsigned-byte 8) values containing a compressed image. If pixel-format is specified, libjpeg-turbo converts output pixel format to a specified value. For the values of pixel-format see the section pixel formats. For more information about flags see the section flags. If scaling-factor is specified librurbo-jpeg will scale the output image to this scaling factor. Possible values are returned by scaling-factors.

Return a decompressed image as a simple-array of (unsigned-byte 8) value in the same manner as cl-jpeg does.

decompress(handle filename &key (scaling-factor 1) (pixel-format rgb) flags)
Decompress an image directly from file with the name filename. See decompress-from-octets for more info
decompress-header-from-octets(handle array)
Decompress header of an image. handle must be a handle to decompressor created with with-decompressor. array must be a simple array of (unsigned-byte 8) values containing compressed jpeg image. Function returns four values:
  1. Width of an image.
  2. Height of an image.
  3. Chroma subsampling. See subsampling section.
  4. Colorspace. See colorspaces section.
decompress-header(handle filename)
This is function is like decompress-header-from-octets but reads compressed image directly from file with the name filename.

In the case of an error all these functions signal jpeg-error condition.

jpeg-error
Errors returned by libjpeg-turbo
  • error-string
    OptionValue
    Allocation:instance
    Type:string
    Initarg::error-string
    Readers:(jpeg-error-string)