libjpeg.turbojpeg

Undocumented in source.

Members

Aliases

tjhandle
alias tjhandle = void*

TurboJPEG instance handle

Enums

TJPF
enum TJPF

Pixel formats

TJSAMP
enum TJSAMP

Chrominance subsampling options. When an image is converted from the RGB to the YUV colorspace as part of the JPEG compression process, some of the U and V (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".

TJXOP
enum TJXOP

Transform operations for #tjTransform()

Functions

TJBUFSIZE
c_ulong TJBUFSIZE(int width, int height)
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJBUFSIZEYUV
c_ulong TJBUFSIZEYUV(int width, int height, int jpegSubsamp)
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJPAD
auto TJPAD(T width)

Pad the given width to the nearest 32-bit boundary

TJSCALED
auto TJSCALED(D dimension, SF scalingFactor)

Compute the scaled value of <tt>dimension</tt> using the given scaling factor. This macro performs the integer equivalent of <tt>ceil(dimension * scalingFactor)</tt>.

tjAlloc
ubyte* 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.)

tjBufSize
c_ulong 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.

tjBufSizeYUV
c_ulong 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.

tjCompress
int tjCompress(tjhandle handle, ubyte* srcBuf, int width, int pitch, int height, int pixelSize, ubyte* dstBuf, c_ulong* compressedSize, int jpegSubsamp, int jpegQual, int flags)
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
tjCompress2
int tjCompress2(tjhandle handle, ubyte* srcBuf, int width, int pitch, int height, int pixelFormat, ubyte** jpegBuf, c_ulong* jpegSize, int jpegSubsamp, int jpegQual, int flags)

* Compress an RGB or grayscale image into a JPEG image. * * @param handle a handle to a TurboJPEG compressor or transformer instance * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels * to be compressed * @param width width (in pixels) of the source image * @param pitch bytes per line of the source image. Normally, this should be * <tt>width * #tjPixelSizepixelFormat</tt> if the image is unpadded, * or <tt>#TJPAD(width * #tjPixelSizepixelFormat)</tt> 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 <tt>width * #tjPixelSizepixelFormat</tt>. * @param height height (in pixels) of the source image * @param pixelFormat pixel format of the source image (see @ref TJPF * "Pixel formats".) * @param 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: * -# pre-allocate the JPEG buffer with an arbitrary size using * #tjAlloc() and let TurboJPEG grow the buffer as needed, * -# set <tt>*jpegBuf</tt> to NULL to tell TurboJPEG to allocate the * buffer for you, or * -# 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, <tt>*jpegSize</tt> should be set to the * size of your pre-allocated buffer. In any case, unless you have * set #TJFLAG_NOREALLOC, you should always check <tt>*jpegBuf</tt> upon * return from this function, as it may have changed. * @param jpegSize pointer to an ulong variable that holds the size of * the JPEG image buffer. If <tt>*jpegBuf</tt> points to a * pre-allocated buffer, then <tt>*jpegSize</tt> should be set to the * size of the buffer. Upon return, <tt>*jpegSize</tt> will contain the * size of the JPEG image (in bytes.) * @param jpegSubsamp the level of chrominance subsampling to be used when * generating the JPEG image (see @ref TJSAMP * "Chrominance subsampling options".) * @param jpegQual the image quality of the generated JPEG image (1 = worst, 100 = best) * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP * "flags". * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)

tjDecompress
int tjDecompress(tjhandle handle, ubyte* jpegBuf, c_ulong jpegSize, ubyte* dstBuf, int width, int pitch, int height, int pixelSize, int flags)
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
tjDecompress2
int tjDecompress2(tjhandle handle, ubyte* jpegBuf, c_ulong jpegSize, ubyte* dstBuf, int width, int pitch, int height, int pixelFormat, int flags)

Decompress a JPEG image to an RGB or grayscale image.

tjDecompressHeader
int tjDecompressHeader(tjhandle handle, ubyte* jpegBuf, c_ulong jpegSize, int* width, int* height)
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
tjDecompressHeader2
int tjDecompressHeader2(tjhandle handle, ubyte* jpegBuf, c_ulong jpegSize, int* width, int* height, int* jpegSubsamp)

* Retrieve information about a JPEG image without decompressing it. * * @param handle a handle to a TurboJPEG decompressor or transformer instance * @param jpegBuf pointer to a buffer containing a JPEG image * @param jpegSize size of the JPEG image (in bytes) * @param width pointer to an integer variable that will receive the width (in * pixels) of the JPEG image * @param height pointer to an integer variable that will receive the height * (in pixels) of the JPEG image * @param jpegSubsamp pointer to an integer variable that will receive the * level of chrominance subsampling used when compressing the JPEG image * (see @ref TJSAMP "Chrominance subsampling options".) * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)

tjDecompressToYUV
int tjDecompressToYUV(tjhandle handle, ubyte* jpegBuf, c_ulong jpegSize, ubyte* 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 in 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.

tjDestroy
int tjDestroy(tjhandle handle)

Destroy a TurboJPEG compressor, decompressor, or transformer instance.

tjEncodeYUV
int tjEncodeYUV(tjhandle handle, ubyte* srcBuf, int width, int pitch, int height, int pixelSize, ubyte* dstBuf, int subsamp, int flags)
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
tjEncodeYUV2
int tjEncodeYUV2(tjhandle handle, ubyte* srcBuf, int width, int pitch, int height, int pixelFormat, ubyte* 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 the * nearest multiple of 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. * * @param handle a handle to a TurboJPEG compressor or transformer instance * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels * to be encoded * @param width width (in pixels) of the source image * @param pitch bytes per line of the source image. Normally, this should be * <tt>width * #tjPixelSizepixelFormat</tt> if the image is unpadded, * or <tt>#TJPAD(width * #tjPixelSizepixelFormat)</tt> 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 <tt>width * #tjPixelSizepixelFormat</tt>. * @param height height (in pixels) of the source image * @param pixelFormat pixel format of the source image (see @ref TJPF * "Pixel formats".) * @param 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. * @param subsamp the level of chrominance subsampling to be used when * generating the YUV image (see @ref TJSAMP * "Chrominance subsampling options".) * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP * "flags". * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)

tjFree
void tjFree(ubyte* 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().

tjGetErrorStr
char* tjGetErrorStr()

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

tjGetScalingFactors
tjscalingfactor* tjGetScalingFactors(int* numscalingfactors)

* Returns a list of fractional scaling factors that the JPEG decompressor in * this implementation of TurboJPEG supports. * * @param numscalingfactors pointer to an integer variable that will receive * the number of elements in the list * * @return a pointer to a list of fractional scaling factors, or NULL if an * error is encountered (see #tjGetErrorStr().)

tjInitCompress
tjhandle tjInitCompress()

Create a TurboJPEG compressor instance.

tjInitDecompress
tjhandle tjInitDecompress()

* Create a TurboJPEG decompressor instance. * * @return a handle to the newly-created instance, or NULL if an error * occurred (see #tjGetErrorStr().)

tjInitTransform
tjhandle tjInitTransform()

Create a new TurboJPEG transformer instance.

tjTransform
int tjTransform(tjhandle handle, ubyte* jpegBuf, c_ulong jpegSize, int n, ubyte** dstBufs, c_ulong* 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 performing Huffman decoding on 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 applying multiple transformations simultaneously, in order to eliminate the need to read the source coefficients multiple times.

Imports

c_ulong (from core.stdc.config)
public import core.stdc.config : c_ulong;

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

Manifest constants

NUMSUBOPT
enum NUMSUBOPT;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJFLAG_ACCURATEDCT
enum TJFLAG_ACCURATEDCT;

Use the most accurate DCT/IDCT algorithm available in the underlying codec. The default if this flag is not specified is implementation-specific. The libjpeg implementation, for example, uses the fast algorithm by default when compressing, because this has been shown to have only a very slight effect on accuracy, but it uses the accurate algorithm when decompressing, because this has been shown to have a larger effect.

TJFLAG_BOTTOMUP
enum TJFLAG_BOTTOMUP;

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

TJFLAG_FASTDCT
enum TJFLAG_FASTDCT;

Use the fastest DCT/IDCT algorithm available in the underlying codec. The default if this flag is not specified is implementation-specific. The libjpeg implementation, for example, uses the fast algorithm by default when compressing, because this has been shown to have only a very slight effect on accuracy, but it uses the accurate algorithm when decompressing, because this has been shown to have a larger effect.

TJFLAG_FASTUPSAMPLE
enum TJFLAG_FASTUPSAMPLE;

When decompressing an image that was compressed using chrominance subsampling, use the fastest chrominance upsampling algorithm available in the underlying codec. The default is to use smooth upsampling, which creates a smooth transition between neighboring chrominance components in order to reduce upsampling artifacts in the decompressed image.

TJFLAG_FORCEMMX
enum TJFLAG_FORCEMMX;

Turn off CPU auto-detection and force TurboJPEG to use MMX code (if the underlying codec supports it.)

TJFLAG_FORCESSE
enum TJFLAG_FORCESSE;

Turn off CPU auto-detection and force TurboJPEG to use SSE code (if the underlying codec supports it.)

TJFLAG_FORCESSE2
enum TJFLAG_FORCESSE2;

Turn off CPU auto-detection and force TurboJPEG to use SSE2 code (if the underlying codec supports it.)

TJFLAG_FORCESSE3
enum TJFLAG_FORCESSE3;

Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (if the underlying codec supports it.)

TJFLAG_NOREALLOC
enum 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.

TJXOPT_CROP
enum TJXOPT_CROP;

This option will enable lossless cropping. See #tjTransform() for more information.

TJXOPT_GRAY
enum TJXOPT_GRAY;

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

TJXOPT_NOOUTPUT
enum 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.)

TJXOPT_PERFECT
enum 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.

TJXOPT_TRIM
enum TJXOPT_TRIM;

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

TJ_411
enum TJ_411;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_420
enum TJ_420;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_422
enum TJ_422;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_444
enum TJ_444;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_ALPHAFIRST
enum TJ_ALPHAFIRST;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_BGR
enum TJ_BGR;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_BOTTOMUP
enum TJ_BOTTOMUP;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_FASTUPSAMPLE
enum TJ_FASTUPSAMPLE;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_FORCEMMX
enum TJ_FORCEMMX;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_FORCESSE
enum TJ_FORCESSE;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_FORCESSE2
enum TJ_FORCESSE2;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_FORCESSE3
enum TJ_FORCESSE3;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_GRAYSCALE
enum TJ_GRAYSCALE;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
TJ_NUMPF
enum TJ_NUMPF;

The number of pixel formats

TJ_NUMSAMP
enum TJ_NUMSAMP;

The number of chrominance subsampling options

TJ_NUMXOP
enum TJ_NUMXOP;

The number of transform operations

TJ_YUV
enum TJ_YUV;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.

Structs

tjregion
struct tjregion

Cropping region

tjscalingfactor
struct tjscalingfactor

Scaling factor

tjtransform
struct tjtransform

Lossless transform

Variables

tjBlueOffset
immutable(int)[TJ_NUMPF] tjBlueOffset;

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 <tt>char pixel[]</tt>, then the blue component will be <tt>pixel[tjBlueOffsetTJ_BGRX]</tt>.

tjGreenOffset
immutable(int)[TJ_NUMPF] tjGreenOffset;

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 <tt>char pixel[]</tt>, then the green component will be <tt>pixel[tjGreenOffsetTJ_BGRX]</tt>.

tjMCUHeight
immutable(int)[TJ_NUMSAMP] tjMCUHeight;

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

tjMCUWidth
immutable(int)[TJ_NUMSAMP] tjMCUWidth;

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

tjPixelSize
immutable(int)[TJ_NUMPF] tjPixelSize;

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

tjRedOffset
immutable(int)[TJ_NUMPF] tjRedOffset;

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 <tt>char pixel[]</tt>, then the red component will be <tt>pixel[tjRedOffsetTJ_BGRX]</tt>.

Meta