TurboJPEG

TurboJPEG API. More...

## Data Structures

struct | tjscalingfactor
| Scaling factor. More...
struct | tjregion
| Cropping region. More...
struct | tjtransform
| Lossless transform. More...

## Defines

#define | TJ_NUMSAMP
| The number of chrominance subsampling options.
#define | TJ_NUMPF
| The number of pixel formats.
#define | TJFLAG_BOTTOMUP
| The uncompressed source/destination image is stored in bottom-up (Windows, OpenGL) order, not top-down (X11) order.
#define | TJFLAG_FORCEMMX
| Turn off CPU auto-detection and force TurboJPEG to use MMX code (IPP and 32-bit libjpeg-turbo versions only.)
#define | TJFLAG_FORCESSE
| Turn off CPU auto-detection and force TurboJPEG to use SSE code (32-bit IPP and 32-bit libjpeg-turbo versions only)
#define | TJFLAG_FORCESSE2
| Turn off CPU auto-detection and force TurboJPEG to use SSE2 code (32-bit IPP and 32-bit libjpeg-turbo versions only)
#define | TJFLAG_FORCESSE3
| Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (64-bit IPP version only)
#define | TJFLAG_FASTUPSAMPLE
| Use fast, inaccurate chrominance upsampling routines in the JPEG decompressor (libjpeg and libjpeg-turbo versions only)
#define | TJFLAG_NOREALLOC
| Disable buffer (re)allocation.
#define | TJ_NUMXOP
| Number of transform operations.
#define | TJXOPT_PERFECT
| This option will cause tjTransform() to return an error if the transform is not perfect.
#define | TJXOPT_TRIM
| This option will cause tjTransform() to discard any partial MCU blocks that cannot be transformed.
#define | TJXOPT_CROP
| This option will enable lossless cropping.
#define | TJXOPT_GRAY
| This option will discard the color data in the input image and produce a grayscale output image.
#define | TJXOPT_NOOUTPUT
| This option will prevent tjTransform() from outputting a JPEG image for this particular transform (this can be used in conjunction with a custom filter to capture the transformed DCT coefficients without transcoding them.)
#define | TJPAD(width)
| Pad the given width to the nearest 32-bit boundary.
#define | TJSCALED(dimension, scalingFactor)
| Compute the scaled value of `dimension` using the given scaling factor.

## Typedefs

typedef struct tjtransform | tjtransform
| Lossless transform.
typedef void * | tjhandle
| TurboJPEG instance handle.

## Enumerations

enum | TJSAMP { TJSAMP_444, TJSAMP_422, TJSAMP_420, TJSAMP_GRAY, TJSAMP_440 }
| Chrominance subsampling options. More...
enum | TJPF { TJPF_RGB, TJPF_BGR, TJPF_RGBX, TJPF_BGRX, TJPF_XBGR, TJPF_XRGB, TJPF_GRAY, TJPF_RGBA, TJPF_BGRA, TJPF_ABGR, TJPF_ARGB }
| Pixel formats. More...
enum | TJXOP { TJXOP_NONE, TJXOP_HFLIP, TJXOP_VFLIP, TJXOP_TRANSPOSE, TJXOP_TRANSVERSE, TJXOP_ROT90, TJXOP_ROT180, TJXOP_ROT270 }
| Transform operations for tjTransform() More...

## Functions

DLLEXPORT tjhandle DLLCALL | tjInitCompress (void)
| Create a TurboJPEG compressor instance.
DLLEXPORT int DLLCALL | tjCompress2 (tjhandle handle, unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char **jpegBuf, unsigned long *jpegSize, int jpegSubsamp, int jpegQual, int flags)
| Compress an RGB or grayscale image into a JPEG image.
DLLEXPORT unsigned long DLLCALL | tjBufSize (int width, int height, int jpegSubsamp)
| The maximum size of the buffer (in bytes) required to hold a JPEG image with the given parameters.
DLLEXPORT unsigned long DLLCALL | tjBufSizeYUV (int width, int height, int subsamp)
| The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters.
DLLEXPORT int DLLCALL | tjEncodeYUV2 (tjhandle handle, unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char *dstBuf, int subsamp, int flags)
| Encode an RGB or grayscale image into a YUV planar image.
DLLEXPORT tjhandle DLLCALL | tjInitDecompress (void)
| Create a TurboJPEG decompressor instance.
DLLEXPORT int DLLCALL | tjDecompressHeader2 (tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height, int *jpegSubsamp)
| Retrieve information about a JPEG image without decompressing it.
DLLEXPORT tjscalingfactor *DLLCALL | tjGetScalingFactors (int *numscalingfactors)
| Returns a list of fractional scaling factors that the JPEG decompressor in this implementation of TurboJPEG supports.
DLLEXPORT int DLLCALL | tjDecompress2 (tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, int width, int pitch, int height, int pixelFormat, int flags)
| Decompress a JPEG image to an RGB or grayscale image.
DLLEXPORT int DLLCALL | tjDecompressToYUV (tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, int flags)
| Decompress a JPEG image to a YUV planar image.
DLLEXPORT tjhandle DLLCALL | tjInitTransform (void)
| Create a new TurboJPEG transformer instance.
DLLEXPORT int DLLCALL | tjTransform (tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int n, unsigned char **dstBufs, unsigned long *dstSizes, tjtransform *transforms, int flags)
| Losslessly transform a JPEG image into another JPEG image.
DLLEXPORT int DLLCALL | tjDestroy (tjhandle handle)
| Destroy a TurboJPEG compressor, decompressor, or transformer instance.
DLLEXPORT unsigned char *DLLCALL | tjAlloc (int bytes)
| Allocate an image buffer for use with TurboJPEG.
DLLEXPORT void DLLCALL | tjFree (unsigned char *buffer)
| Free an image buffer previously allocated by TurboJPEG.
DLLEXPORT char *DLLCALL | tjGetErrorStr (void)
| Returns a descriptive error message explaining why the last command failed.

## Variables

static const int | tjMCUWidth [TJ_NUMSAMP]
| MCU block width (in pixels) for a given level of chrominance subsampling.
static const int | tjMCUHeight [TJ_NUMSAMP]
| MCU block height (in pixels) for a given level of chrominance subsampling.
static const int | tjRedOffset [TJ_NUMPF]
| Red offset (in bytes) for a given pixel format.
static const int | tjGreenOffset [TJ_NUMPF]
| Green offset (in bytes) for a given pixel format.
static const int | tjBlueOffset [TJ_NUMPF]
| Blue offset (in bytes) for a given pixel format.
static const int | tjPixelSize [TJ_NUMPF]
| Pixel size (in bytes) for a given pixel format.

## Detailed Description

TurboJPEG API.

This API provides an interface for generating, decoding, and transforming planar YUV and JPEG images in memory.

## Define Documentation

#define TJ_NUMPF

The number of pixel formats.

#define TJ_NUMSAMP

The number of chrominance subsampling options.

#define TJ_NUMXOP

Number of transform operations.

#define TJFLAG_BOTTOMUP

The uncompressed source/destination image is stored in bottom-up (Windows, OpenGL) order, not top-down (X11) order.

#define TJFLAG_FASTUPSAMPLE

Use fast, inaccurate chrominance upsampling routines in the JPEG decompressor (libjpeg and libjpeg-turbo versions only)

#define TJFLAG_FORCEMMX

Turn off CPU auto-detection and force TurboJPEG to use MMX code (IPP and 32-bit libjpeg-turbo versions only.)

#define TJFLAG_FORCESSE

Turn off CPU auto-detection and force TurboJPEG to use SSE code (32-bit IPP and 32-bit libjpeg-turbo versions only)

#define TJFLAG_FORCESSE2

Turn off CPU auto-detection and force TurboJPEG to use SSE2 code (32-bit IPP and 32-bit libjpeg-turbo versions only)

#define TJFLAG_FORCESSE3

Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (64-bit IPP version only)

#define TJFLAG_NOREALLOC

Disable buffer (re)allocation.

If passed to tjCompress2() or tjTransform(), this flag will cause those functions to generate an error if the JPEG image buffer is invalid or too small rather than attempting to allocate or reallocate that buffer. This reproduces the behavior of earlier versions of TurboJPEG.

#define TJPAD | ( |  | width | ) |

Pad the given width to the nearest 32-bit boundary.

#define TJSCALED | ( |  | dimension,
|  |  | scalingFactor
| ) |  |

Compute the scaled value of `dimension` using the given scaling factor.

This macro performs the integer equivalent of `ceil(dimension * scalingFactor)`.

#define TJXOPT_CROP

This option will enable lossless cropping.

See tjTransform() for more information.

#define TJXOPT_GRAY

This option will discard the color data in the input image and produce a grayscale output image.

#define TJXOPT_NOOUTPUT

This option will prevent tjTransform() from outputting a JPEG image for this particular transform (this can be used in conjunction with a custom filter to capture the transformed DCT coefficients without transcoding them.)

#define TJXOPT_PERFECT

This option will cause tjTransform() to return an error if the transform is not perfect.

Lossless transforms operate on MCU blocks, whose size depends on the level of chrominance subsampling used (see tjMCUWidth and tjMCUHeight.) If the image's width or height is not evenly divisible by the MCU block size, then there will be partial MCU blocks on the right and/or bottom edges. It is not possible to move these partial MCU blocks to the top or left of the image, so any transform that would require that is "imperfect." If this option is not specified, then any partial MCU blocks that cannot be transformed will be left in place, which will create odd-looking strips on the right or bottom edge of the image.

#define TJXOPT_TRIM

This option will cause tjTransform() to discard any partial MCU blocks that cannot be transformed.

## Typedef Documentation

typedef void* tjhandle

TurboJPEG instance handle.

typedef struct tjtransform tjtransform

Lossless transform.

## Enumeration Type Documentation

enum TJPF

Pixel formats.

Enumerator:

  TJPF_RGB | RGB pixel format. The red, green, and blue components in the image are stored in 3-byte pixels in the order R, G, B from lowest to highest byte address within each pixel.
  TJPF_BGR | BGR pixel format. The red, green, and blue components in the image are stored in 3-byte pixels in the order B, G, R from lowest to highest byte address within each pixel.
  TJPF_RGBX | RGBX pixel format. The red, green, and blue components in the image are stored in 4-byte pixels in the order R, G, B from lowest to highest byte address within each pixel. The X component is ignored when compressing and undefined when decompressing.
  TJPF_BGRX | BGRX pixel format. The red, green, and blue components in the image are stored in 4-byte pixels in the order B, G, R from lowest to highest byte address within each pixel. The X component is ignored when compressing and undefined when decompressing.
  TJPF_XBGR | XBGR pixel format. The red, green, and blue components in the image are stored in 4-byte pixels in the order R, G, B from highest to lowest byte address within each pixel. The X component is ignored when compressing and undefined when decompressing.
  TJPF_XRGB | XRGB pixel format. The red, green, and blue components in the image are stored in 4-byte pixels in the order B, G, R from highest to lowest byte address within each pixel. The X component is ignored when compressing and undefined when decompressing.
  TJPF_GRAY | Grayscale pixel format. Each 1-byte pixel represents a luminance (brightness) level from 0 to 255.
  TJPF_RGBA | RGBA pixel format. This is the same as TJPF_RGBX, except that when decompressing, the X component is guaranteed to be 0xFF, which can be interpreted as an opaque alpha channel.
  TJPF_BGRA | BGRA pixel format. This is the same as TJPF_BGRX, except that when decompressing, the X component is guaranteed to be 0xFF, which can be interpreted as an opaque alpha channel.
  TJPF_ABGR | ABGR pixel format. This is the same as TJPF_XBGR, except that when decompressing, the X component is guaranteed to be 0xFF, which can be interpreted as an opaque alpha channel.
  TJPF_ARGB | ARGB pixel format. This is the same as TJPF_XRGB, except that when decompressing, the X component is guaranteed to be 0xFF, which can be interpreted as an opaque alpha channel.

enum TJSAMP

Chrominance subsampling options.

When an image is converted from the RGB to the YCbCr colorspace as part of the JPEG compression process, some of the Cb and Cr (chrominance) components can be discarded or averaged together to produce a smaller image with little perceptible loss of image clarity (the human eye is more sensitive to small changes in brightness than small changes in color.) This is called "chrominance subsampling".

Enumerator:

  TJSAMP_444 | 4:4:4 chrominance subsampling (no chrominance subsampling). The JPEG or YUV image will contain one chrominance component for every pixel in the source image.
  TJSAMP_422 | 4:2:2 chrominance subsampling. The JPEG or YUV image will contain one chrominance component for every 2x1 block of pixels in the source image.
  TJSAMP_420 | 4:2:0 chrominance subsampling. The JPEG or YUV image will contain one chrominance component for every 2x2 block of pixels in the source image.
  TJSAMP_GRAY | Grayscale. The JPEG or YUV image will contain no chrominance components.
  TJSAMP_440 | 4:4:0 chrominance subsampling. The JPEG or YUV image will contain one chrominance component for every 1x2 block of pixels in the source image.

enum TJXOP

Transform operations for tjTransform()

Enumerator:

  TJXOP_NONE | Do not transform the position of the image pixels.
  TJXOP_HFLIP | Flip (mirror) image horizontally. This transform is imperfect if there are any partial MCU blocks on the right edge (see TJXOPT_PERFECT.)
  TJXOP_VFLIP | Flip (mirror) image vertically. This transform is imperfect if there are any partial MCU blocks on the bottom edge (see TJXOPT_PERFECT.)
  TJXOP_TRANSPOSE | Transpose image (flip/mirror along upper left to lower right axis.) This transform is always perfect.
  TJXOP_TRANSVERSE | Transverse transpose image (flip/mirror along upper right to lower left axis.) This transform is imperfect if there are any partial MCU blocks in the image (see TJXOPT_PERFECT.)
  TJXOP_ROT90 | Rotate image clockwise by 90 degrees. This transform is imperfect if there are any partial MCU blocks on the bottom edge (see TJXOPT_PERFECT.)
  TJXOP_ROT180 | Rotate image 180 degrees. This transform is imperfect if there are any partial MCU blocks in the image (see TJXOPT_PERFECT.)
  TJXOP_ROT270 | Rotate image counter-clockwise by 90 degrees. This transform is imperfect if there are any partial MCU blocks on the right edge (see TJXOPT_PERFECT.)

## Function Documentation

DLLEXPORT unsigned char* DLLCALL tjAlloc | ( | int | bytes | ) |

Allocate an image buffer for use with TurboJPEG.

You should always use this function to allocate the JPEG destination buffer(s) for tjCompress2() and tjTransform() unless you are disabling automatic buffer (re)allocation (by setting TJFLAG_NOREALLOC.)

Parameters:

  bytes | the number of bytes to allocate

Returns:
  a pointer to a newly-allocated buffer with the specified number of bytes

See also:
  tjFree()

DLLEXPORT unsigned long DLLCALL tjBufSize | ( | int | width,
|  | int | height,
|  | int | jpegSubsamp
| ) |  |

The maximum size of the buffer (in bytes) required to hold a JPEG image with the given parameters.

The number of bytes returned by this function is larger than the size of the uncompressed source image. The reason for this is that the JPEG format uses 16-bit coefficients, and it is thus possible for a very high-quality JPEG image with very high frequency content to expand rather than compress when converted to the JPEG format. Such images represent a very rare corner case, but since there is no way to predict the size of a JPEG image prior to compression, the corner case has to be handled.

Parameters:

  width | width of the image (in pixels)
  height | height of the image (in pixels)
  jpegSubsamp | the level of chrominance subsampling to be used when generating the JPEG image (see Chrominance subsampling options.)

Returns:
  the maximum size of the buffer (in bytes) required to hold the image, or -1 if the arguments are out of bounds.

DLLEXPORT unsigned long DLLCALL tjBufSizeYUV | ( | int | width,
|  | int | height,
|  | int | subsamp
| ) |  |

The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters.

Parameters:

  width | width of the image (in pixels)
  height | height of the image (in pixels)
  subsamp | level of chrominance subsampling in the image (see Chrominance subsampling options.)

Returns:
  the size of the buffer (in bytes) required to hold the image, or -1 if the arguments are out of bounds.

DLLEXPORT int DLLCALL tjCompress2 | ( | tjhandle | handle,
|  | unsigned char * | srcBuf,
|  | int | width,
|  | int | pitch,
|  | int | height,
|  | int | pixelFormat,
|  | unsigned char ** | jpegBuf,
|  | unsigned long * | jpegSize,
|  | int | jpegSubsamp,
|  | int | jpegQual,
|  | int | flags
| ) |  |

Compress an RGB or grayscale image into a JPEG image.

Parameters:

  handle | a handle to a TurboJPEG compressor or transformer instance
  srcBuf | pointer to an image buffer containing RGB or grayscale pixels to be compressed
  width | width (in pixels) of the source image

  pitch

  bytes per line of the source image. Normally, this should be `width * tjPixelSize[pixelFormat]` if the image is unpadded, or `TJPAD(width * tjPixelSize[pixelFormat])` if each line of the image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to `width * tjPixelSize[pixelFormat]`.

  height | height (in pixels) of the source image
  pixelFormat | pixel format of the source image (see Pixel formats.)

  jpegBuf

  address of a pointer to an image buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:
  1. pre-allocate the JPEG buffer with an arbitrary size using tjAlloc() and let TurboJPEG grow the buffer as needed,
  2. set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you, or
  3. pre-allocate the buffer to a "worst case" size determined by calling tjBufSize(). This should ensure that the buffer never has to be re-allocated (setting TJFLAG_NOREALLOC guarantees this.)
  If you choose option 1, `*jpegSize` should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check `*jpegBuf` upon return from this function, as it may have changed.

  jpegSize | pointer to an unsigned long variable that holds the size of the JPEG image buffer. If `*jpegBuf` points to a pre-allocated buffer, then `*jpegSize` should be set to the size of the buffer. Upon return, `*jpegSize` will contain the size of the JPEG image (in bytes.)
  jpegSubsamp | the level of chrominance subsampling to be used when generating the JPEG image (see Chrominance subsampling options.)
  jpegQual | the image quality of the generated JPEG image (1 = worst, 100 = best)
  flags | the bitwise OR of one or more of the flags.

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

DLLEXPORT int DLLCALL tjDecompress2 | ( | tjhandle | handle,
|  | unsigned char * | jpegBuf,
|  | unsigned long | jpegSize,
|  | unsigned char * | dstBuf,
|  | int | width,
|  | int | pitch,
|  | int | height,
|  | int | pixelFormat,
|  | int | flags
| ) |  |

Decompress a JPEG image to an RGB or grayscale image.

Parameters:

  handle | a handle to a TurboJPEG decompressor or transformer instance
  jpegBuf | pointer to a buffer containing the JPEG image to decompress
  jpegSize | size of the JPEG image (in bytes)
  dstBuf | pointer to an image buffer that will receive the decompressed image. This buffer should normally be `pitch * scaledHeight` bytes in size, where `scaledHeight` can be determined by calling TJSCALED() with the JPEG image height and one of the scaling factors returned by tjGetScalingFactors(). The dstBuf pointer may also be used to decompress into a specific region of a larger buffer.
  width | desired width (in pixels) of the destination image. If this is smaller than the width of the JPEG image being decompressed, then TurboJPEG will use scaling in the JPEG decompressor to generate the largest possible image that will fit within the desired width. If width is set to 0, then only the height will be considered when determining the scaled image size.

  pitch

  bytes per line of the destination image. Normally, this is `scaledWidth * tjPixelSize[pixelFormat]` if the decompressed image is unpadded, else `TJPAD(scaledWidth * tjPixelSize[pixelFormat])` if each line of the decompressed image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. (NOTE: `scaledWidth` can be determined by calling TJSCALED() with the JPEG image width and one of the scaling factors returned by tjGetScalingFactors().) You can also be clever and use the pitch parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to `scaledWidth * tjPixelSize[pixelFormat]`.

  height | desired height (in pixels) of the destination image. If this is smaller than the height of the JPEG image being decompressed, then TurboJPEG will use scaling in the JPEG decompressor to generate the largest possible image that will fit within the desired height. If height is set to 0, then only the width will be considered when determining the scaled image size.
  pixelFormat | pixel format of the destination image (see Pixel formats.)
  flags | the bitwise OR of one or more of the flags.

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

DLLEXPORT int DLLCALL tjDecompressHeader2 | ( | tjhandle | handle,
|  | unsigned char * | jpegBuf,
|  | unsigned long | jpegSize,
|  | int * | width,
|  | int * | height,
|  | int * | jpegSubsamp
| ) |  |

Retrieve information about a JPEG image without decompressing it.

Parameters:

  handle | a handle to a TurboJPEG decompressor or transformer instance
  jpegBuf | pointer to a buffer containing a JPEG image
  jpegSize | size of the JPEG image (in bytes)
  width | pointer to an integer variable that will receive the width (in pixels) of the JPEG image
  height | pointer to an integer variable that will receive the height (in pixels) of the JPEG image
  jpegSubsamp | pointer to an integer variable that will receive the level of chrominance subsampling used when compressing the JPEG image (see Chrominance subsampling options.)

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

DLLEXPORT int DLLCALL tjDecompressToYUV | ( | tjhandle | handle,
|  | unsigned char * | jpegBuf,
|  | unsigned long | jpegSize,
|  | unsigned char * | dstBuf,
|  | int | flags
| ) |  |

Decompress a JPEG image to a YUV planar image.

This function performs JPEG decompression but leaves out the color conversion step, so a planar YUV image is generated instead of an RGB image. The padding of the planes in this image is the same as the images generated by tjEncodeYUV2(). Note that, if the width or height of the image is not an even multiple of the MCU block size (see tjMCUWidth and tjMCUHeight), then an intermediate buffer copy will be performed within TurboJPEG.

Parameters:

  handle | a handle to a TurboJPEG decompressor or transformer instance
  jpegBuf | pointer to a buffer containing the JPEG image to decompress
  jpegSize | size of the JPEG image (in bytes)
  dstBuf | pointer to an image buffer that will receive the YUV image. Use tjBufSizeYUV to determine the appropriate size for this buffer based on the image width, height, and level of subsampling.
  flags | the bitwise OR of one or more of the flags.

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

DLLEXPORT int DLLCALL tjDestroy | ( | tjhandle | handle | ) |

Destroy a TurboJPEG compressor, decompressor, or transformer instance.

Parameters:

  handle | a handle to a TurboJPEG compressor, decompressor or transformer instance

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

DLLEXPORT int DLLCALL tjEncodeYUV2 | ( | tjhandle | handle,
|  | unsigned char * | srcBuf,
|  | int | width,
|  | int | pitch,
|  | int | height,
|  | int | pixelFormat,
|  | unsigned char * | dstBuf,
|  | int | subsamp,
|  | int | flags
| ) |  |

Encode an RGB or grayscale image into a YUV planar image.

This function uses the accelerated color conversion routines in TurboJPEG's underlying codec to produce a planar YUV image that is suitable for X Video. Specifically, if the chrominance components are subsampled along the horizontal dimension, then the width of the luminance plane is padded to 2 in the output image (same goes for the height of the luminance plane, if the chrominance components are subsampled along the vertical dimension.) Also, each line of each plane in the output image is padded to 4 bytes. Although this will work with any subsampling option, it is really only useful in combination with TJ_420, which produces an image compatible with the I420 (AKA "YUV420P") format.

Parameters:

  handle | a handle to a TurboJPEG compressor or transformer instance
  srcBuf | pointer to an image buffer containing RGB or grayscale pixels to be encoded
  width | width (in pixels) of the source image

  pitch

  bytes per line of the source image. Normally, this should be `width * tjPixelSize[pixelFormat]` if the image is unpadded, or `TJPAD(width * tjPixelSize[pixelFormat])` if each line of the image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to `width * tjPixelSize[pixelFormat]`.

  height | height (in pixels) of the source image
  pixelFormat | pixel format of the source image (see Pixel formats.)
  dstBuf | pointer to an image buffer that will receive the YUV image. Use tjBufSizeYUV() to determine the appropriate size for this buffer based on the image width, height, and level of chrominance subsampling.
  subsamp | the level of chrominance subsampling to be used when generating the YUV image (see Chrominance subsampling options.)
  flags | the bitwise OR of one or more of the flags.

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

DLLEXPORT void DLLCALL tjFree | ( | unsigned char * | buffer | ) |

Free an image buffer previously allocated by TurboJPEG.

You should always use this function to free JPEG destination buffer(s) that were automatically (re)allocated by tjCompress2() or tjTransform() or that were manually allocated using tjAlloc().

Parameters:

  buffer | address of the buffer to free

See also:
  tjAlloc()

DLLEXPORT char* DLLCALL tjGetErrorStr | ( | void |  | ) |

Returns a descriptive error message explaining why the last command failed.

Returns:
  a descriptive error message explaining why the last command failed.

DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors | ( | int * | numscalingfactors | ) |

Returns a list of fractional scaling factors that the JPEG decompressor in this implementation of TurboJPEG supports.

Parameters:

  numscalingfactors | pointer to an integer variable that will receive the number of elements in the list

Returns:
  a pointer to a list of fractional scaling factors, or NULL if an error is encountered (see tjGetErrorStr().)

DLLEXPORT tjhandle DLLCALL tjInitCompress | ( | void |  | ) |

Create a TurboJPEG compressor instance.

Returns:
  a handle to the newly-created instance, or NULL if an error occurred (see tjGetErrorStr().)

DLLEXPORT tjhandle DLLCALL tjInitDecompress | ( | void |  | ) |

Create a TurboJPEG decompressor instance.

Returns:
  a handle to the newly-created instance, or NULL if an error occurred (see tjGetErrorStr().)

DLLEXPORT tjhandle DLLCALL tjInitTransform | ( | void |  | ) |

Create a new TurboJPEG transformer instance.

Returns:
  a handle to the newly-created instance, or NULL if an error occurred (see tjGetErrorStr().)

DLLEXPORT int DLLCALL tjTransform | ( | tjhandle | handle,
|  | unsigned char * | jpegBuf,
|  | unsigned long | jpegSize,
|  | int | n,
|  | unsigned char ** | dstBufs,
|  | unsigned long * | dstSizes,
|  | tjtransform * | transforms,
|  | int | flags
| ) |  |

Losslessly transform a JPEG image into another JPEG image.

Lossless transforms work by moving the raw coefficients from one JPEG image structure to another without altering the values of the coefficients. While this is typically faster than decompressing the image, transforming it, and re-compressing it, lossless transforms are not free. Each lossless transform requires reading and Huffman decoding all of the coefficients in the source image, regardless of the size of the destination image. Thus, this function provides a means of generating multiple transformed images from the same source or of applying multiple transformations simultaneously, in order to eliminate the need to read the source coefficients multiple times.

Parameters:

  handle | a handle to a TurboJPEG transformer instance
  jpegBuf | pointer to a buffer containing the JPEG image to transform
  jpegSize | size of the JPEG image (in bytes)
  n | the number of transformed JPEG images to generate

  dstBufs

  pointer to an array of n image buffers. `dstBufs[i]` will receive a JPEG image that has been transformed using the parameters in `transforms[i]`. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:
  1. pre-allocate the JPEG buffer with an arbitrary size using tjAlloc() and let TurboJPEG grow the buffer as needed,
  2. set `dstBufs[i]` to NULL to tell TurboJPEG to allocate the buffer for you, or
  3. pre-allocate the buffer to a "worst case" size determined by calling tjBufSize() with the cropped width and height. This should ensure that the buffer never has to be re-allocated (setting TJFLAG_NOREALLOC guarantees this.)
  If you choose option 1, `dstSizes[i]` should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check `dstBufs[i]` upon return from this function, as it may have changed.

  dstSizes | pointer to an array of n unsigned long variables that will receive the actual sizes (in bytes) of each transformed JPEG image. If `dstBufs[i]` points to a pre-allocated buffer, then `dstSizes[i]` should be set to the size of the buffer. Upon return, `dstSizes[i]` will contain the size of the JPEG image (in bytes.)
  transforms | pointer to an array of n tjtransform structures, each of which specifies the transform parameters and/or cropping region for the corresponding transformed output image.
  flags | the bitwise OR of one or more of the flags.

Returns:
  0 if successful, or -1 if an error occurred (see tjGetErrorStr().)

## Variable Documentation

const int tjBlueOffset[TJ_NUMPF]`[static]`

Blue offset (in bytes) for a given pixel format.

This specifies the number of bytes that the Blue component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRX is stored in `char pixel[]`, then the blue component will be `pixel[tjBlueOffset[TJ_BGRX]]`.

const int tjGreenOffset[TJ_NUMPF]`[static]`

Green offset (in bytes) for a given pixel format.

This specifies the number of bytes that the green component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRX is stored in `char pixel[]`, then the green component will be `pixel[tjGreenOffset[TJ_BGRX]]`.

const int tjMCUHeight[TJ_NUMSAMP]`[static]`

MCU block height (in pixels) for a given level of chrominance subsampling.

MCU block sizes:

- 8x8 for no subsampling or grayscale
- 16x8 for 4:2:2
- 8x16 for 4:4:0
- 16x16 for 4:2:0

const int tjMCUWidth[TJ_NUMSAMP]`[static]`

MCU block width (in pixels) for a given level of chrominance subsampling.

MCU block sizes:

- 8x8 for no subsampling or grayscale
- 16x8 for 4:2:2
- 8x16 for 4:4:0
- 16x16 for 4:2:0

const int tjPixelSize[TJ_NUMPF]`[static]`

Pixel size (in bytes) for a given pixel format.

const int tjRedOffset[TJ_NUMPF]`[static]`

Red offset (in bytes) for a given pixel format.

This specifies the number of bytes that the red component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRX is stored in `char pixel[]`, then the red component will be `pixel[tjRedOffset[TJ_BGRX]]`.

All Data Structures Variables