TJ: Reorder functions to improve readability
Put all general functions at the top of the list, and ensure that all functions are defined before they are mentioned. Also consistify the function ordering between turbojpeg.h and turbojpeg.c
This commit is contained in:
DRC
694
turbojpeg.h
694
turbojpeg.h
@@ -1184,6 +1184,40 @@ extern "C" {
|
||||
DLLEXPORT tjhandle tj3Init(int initType);
|
||||
|
||||
|
||||
/**
|
||||
* Destroy a TurboJPEG instance.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance. If the handle is NULL, then
|
||||
* this function has no effect.
|
||||
*/
|
||||
DLLEXPORT void tj3Destroy(tjhandle handle);
|
||||
|
||||
|
||||
/**
|
||||
* Returns a descriptive error message explaining why the last command failed.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance, or NULL if the error was
|
||||
* generated by a global function (but note that retrieving the error message
|
||||
* for a global function is thread-safe only on platforms that support
|
||||
* thread-local storage.)
|
||||
*
|
||||
* @return a descriptive error message explaining why the last command failed.
|
||||
*/
|
||||
DLLEXPORT char *tj3GetErrorStr(tjhandle handle);
|
||||
|
||||
|
||||
/**
|
||||
* Returns a code indicating the severity of the last error. See
|
||||
* @ref TJERR "Error codes".
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance
|
||||
*
|
||||
* @return a code indicating the severity of the last error. See
|
||||
* @ref TJERR "Error codes".
|
||||
*/
|
||||
DLLEXPORT int tj3GetErrorCode(tjhandle handle);
|
||||
|
||||
|
||||
/**
|
||||
* Set the value of a parameter.
|
||||
*
|
||||
@@ -1212,204 +1246,33 @@ DLLEXPORT int tj3Get(tjhandle handle, int param);
|
||||
|
||||
|
||||
/**
|
||||
* Compress an 8-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into
|
||||
* an 8-bit-per-sample JPEG image.
|
||||
* Allocate a byte buffer for use with TurboJPEG. You should always use this
|
||||
* function to allocate the JPEG destination buffer(s) for the compression and
|
||||
* transform functions unless you are disabling automatic buffer (re)allocation
|
||||
* (by setting #TJPARAM_NOREALLOC.)
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
* @param bytes the number of bytes to allocate
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a packed-pixel RGB, grayscale,
|
||||
* or CMYK source image to be compressed. This buffer should normally be
|
||||
* `pitch * height` samples in size. However, you can also use this parameter
|
||||
* to compress from a specific region of a larger buffer.
|
||||
* @return a pointer to a newly-allocated buffer with the specified number of
|
||||
* bytes.
|
||||
*
|
||||
* @param width width (in pixels) of the source image
|
||||
*
|
||||
* @param pitch samples per row in the source image. Normally this should be
|
||||
* <tt>width * #tjPixelSize[pixelFormat]</tt>, if the image is unpadded.
|
||||
* (Setting this parameter to 0 is the equivalent of setting it to
|
||||
* <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can also use this
|
||||
* parameter to specify the row alignment/padding of the source image, to skip
|
||||
* rows, or to compress from a specific region of a larger buffer.
|
||||
*
|
||||
* @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 a byte 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 #tj3Alloc() and
|
||||
* let TurboJPEG grow the buffer as needed,
|
||||
* -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you,
|
||||
* or
|
||||
* -# pre-allocate the buffer to a "worst case" size determined by calling
|
||||
* #tj3JPEGBufSize(). This should ensure that the buffer never has to be
|
||||
* re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.)
|
||||
* .
|
||||
* If you choose option 1, then `*jpegSize` should be set to the size of your
|
||||
* pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC,
|
||||
* you should always check `*jpegBuf` upon return from this function, as it may
|
||||
* have changed.
|
||||
*
|
||||
* @param jpegSize pointer to a size_t variable that holds the size of the JPEG
|
||||
* 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.) If `*jpegBuf` points to a
|
||||
* JPEG buffer that is being reused from a previous call to one of the JPEG
|
||||
* compression functions, then `*jpegSize` is ignored.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
* @see tj3Free()
|
||||
*/
|
||||
DLLEXPORT int tj3Compress8(tjhandle handle, const unsigned char *srcBuf,
|
||||
int width, int pitch, int height, int pixelFormat,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
/**
|
||||
* Compress a 12-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into
|
||||
* a 12-bit-per-sample JPEG image.
|
||||
*
|
||||
* \details \copydetails tj3Compress8()
|
||||
*/
|
||||
DLLEXPORT int tj3Compress12(tjhandle handle, const short *srcBuf, int width,
|
||||
int pitch, int height, int pixelFormat,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
/**
|
||||
* Compress a 16-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into
|
||||
* a 16-bit-per-sample lossless JPEG image.
|
||||
*
|
||||
* \details \copydetails tj3Compress8()
|
||||
*/
|
||||
DLLEXPORT int tj3Compress16(tjhandle handle, const unsigned short *srcBuf,
|
||||
int width, int pitch, int height, int pixelFormat,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
DLLEXPORT void *tj3Alloc(size_t bytes);
|
||||
|
||||
|
||||
/**
|
||||
* Compress an 8-bit-per-sample unified planar YUV image into an
|
||||
* 8-bit-per-sample JPEG image.
|
||||
* Free a byte buffer previously allocated by TurboJPEG. You should always use
|
||||
* this function to free JPEG destination buffer(s) that were automatically
|
||||
* (re)allocated by the compression and transform functions or that were
|
||||
* manually allocated using #tj3Alloc().
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
* @param buffer address of the buffer to free. If the address is NULL, then
|
||||
* this function has no effect.
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a unified planar YUV source
|
||||
* image to be compressed. The size of this buffer should match the value
|
||||
* returned by #tj3YUVBufSize() for the given image width, height, row
|
||||
* alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The
|
||||
* Y, U (Cb), and V (Cr) image planes should be stored sequentially in the
|
||||
* buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".)
|
||||
*
|
||||
* @param width width (in pixels) of the source image. If the width is not an
|
||||
* even multiple of the iMCU width (see #tjMCUWidth), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param align row alignment (in bytes) of the source image (must be a power
|
||||
* of 2.) Setting this parameter to n indicates that each row in each plane of
|
||||
* the source image is padded to the nearest multiple of n bytes
|
||||
* (1 = unpadded.)
|
||||
*
|
||||
* @param height height (in pixels) of the source image. If the height is not
|
||||
* an even multiple of the iMCU height (see #tjMCUHeight), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param jpegBuf address of a pointer to a byte 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 #tj3Alloc() and
|
||||
* let TurboJPEG grow the buffer as needed,
|
||||
* -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you,
|
||||
* or
|
||||
* -# pre-allocate the buffer to a "worst case" size determined by calling
|
||||
* #tj3JPEGBufSize(). This should ensure that the buffer never has to be
|
||||
* re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.)
|
||||
* .
|
||||
* If you choose option 1, then `*jpegSize` should be set to the size of your
|
||||
* pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC,
|
||||
* you should always check `*jpegBuf` upon return from this function, as it may
|
||||
* have changed.
|
||||
*
|
||||
* @param jpegSize pointer to a size_t variable that holds the size of the JPEG
|
||||
* 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.) If `*jpegBuf` points to a
|
||||
* JPEG buffer that is being reused from a previous call to one of the JPEG
|
||||
* compression functions, then `*jpegSize` is ignored.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
* @see tj3Alloc()
|
||||
*/
|
||||
DLLEXPORT int tj3CompressFromYUV8(tjhandle handle,
|
||||
const unsigned char *srcBuf, int width,
|
||||
int align, int height,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
|
||||
/**
|
||||
* Compress a set of 8-bit-per-sample Y, U (Cb), and V (Cr) image planes into
|
||||
* an 8-bit-per-sample JPEG image.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
*
|
||||
* @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes
|
||||
* (or just a Y plane, if compressing a grayscale image) that contain a YUV
|
||||
* source image to be compressed. These planes can be contiguous or
|
||||
* non-contiguous in memory. The size of each plane should match the value
|
||||
* returned by #tj3YUVPlaneSize() for the given image width, height, strides,
|
||||
* and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) Refer to
|
||||
* @ref YUVnotes "YUV Image Format Notes" for more details.
|
||||
*
|
||||
* @param width width (in pixels) of the source image. If the width is not an
|
||||
* even multiple of the iMCU width (see #tjMCUWidth), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param strides an array of integers, each specifying the number of bytes per
|
||||
* row in the corresponding plane of the YUV source image. Setting the stride
|
||||
* for any plane to 0 is the same as setting it to the plane width (see
|
||||
* @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the
|
||||
* strides for all planes will be set to their respective plane widths. You
|
||||
* can adjust the strides in order to specify an arbitrary amount of row
|
||||
* padding in each plane or to create a JPEG image from a subregion of a larger
|
||||
* planar YUV image.
|
||||
*
|
||||
* @param height height (in pixels) of the source image. If the height is not
|
||||
* an even multiple of the iMCU height (see #tjMCUHeight), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param jpegBuf address of a pointer to a byte 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 #tj3Alloc() and
|
||||
* let TurboJPEG grow the buffer as needed,
|
||||
* -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you,
|
||||
* or
|
||||
* -# pre-allocate the buffer to a "worst case" size determined by calling
|
||||
* #tj3JPEGBufSize(). This should ensure that the buffer never has to be
|
||||
* re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.)
|
||||
* .
|
||||
* If you choose option 1, then `*jpegSize` should be set to the size of your
|
||||
* pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC,
|
||||
* you should always check `*jpegBuf` upon return from this function, as it may
|
||||
* have changed.
|
||||
*
|
||||
* @param jpegSize pointer to a size_t variable that holds the size of the JPEG
|
||||
* 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.) If `*jpegBuf` points to a
|
||||
* JPEG buffer that is being reused from a previous call to one of the JPEG
|
||||
* compression functions, then `*jpegSize` is ignored.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3CompressFromYUVPlanes8(tjhandle handle,
|
||||
const unsigned char * const *srcPlanes,
|
||||
int width, const int *strides,
|
||||
int height, unsigned char **jpegBuf,
|
||||
size_t *jpegSize);
|
||||
DLLEXPORT void tj3Free(void *buffer);
|
||||
|
||||
|
||||
/**
|
||||
@@ -1522,51 +1385,204 @@ DLLEXPORT int tj3YUVPlaneHeight(int componentID, int height, int subsamp);
|
||||
|
||||
|
||||
/**
|
||||
* Encode an 8-bit-per-sample packed-pixel RGB or grayscale image into an
|
||||
* 8-bit-per-sample unified planar YUV image. This function performs color
|
||||
* conversion (which is accelerated in the libjpeg-turbo implementation) but
|
||||
* does not execute any of the other steps in the JPEG compression process.
|
||||
* Compress an 8-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into
|
||||
* an 8-bit-per-sample JPEG image.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a packed-pixel RGB or grayscale
|
||||
* source image to be encoded. This buffer should normally be `pitch * height`
|
||||
* bytes in size. However, you can also use this parameter to encode from a
|
||||
* specific region of a larger buffer.
|
||||
* @param srcBuf pointer to a buffer containing a packed-pixel RGB, grayscale,
|
||||
* or CMYK source image to be compressed. This buffer should normally be
|
||||
* `pitch * height` samples in size. However, you can also use this parameter
|
||||
* to compress from a specific region of a larger buffer.
|
||||
*
|
||||
* @param width width (in pixels) of the source image
|
||||
*
|
||||
* @param pitch bytes per row in the source image. Normally this should be
|
||||
* @param pitch samples per row in the source image. Normally this should be
|
||||
* <tt>width * #tjPixelSize[pixelFormat]</tt>, if the image is unpadded.
|
||||
* (Setting this parameter to 0 is the equivalent of setting it to
|
||||
* <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can also use this
|
||||
* parameter to specify the row alignment/padding of the source image, to skip
|
||||
* rows, or to encode from a specific region of a larger packed-pixel image.
|
||||
* rows, or to compress from a specific region of a larger buffer.
|
||||
*
|
||||
* @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 a buffer that will receive the unified planar YUV
|
||||
* image. Use #tj3YUVBufSize() to determine the appropriate size for this
|
||||
* buffer based on the image width, height, row alignment, and level of
|
||||
* chrominance subsampling (see #TJPARAM_SUBSAMP.) The Y, U (Cb), and V (Cr)
|
||||
* image planes will be stored sequentially in the buffer. (Refer to
|
||||
* @ref YUVnotes "YUV Image Format Notes".)
|
||||
* @param jpegBuf address of a pointer to a byte 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 #tj3Alloc() and
|
||||
* let TurboJPEG grow the buffer as needed,
|
||||
* -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you,
|
||||
* or
|
||||
* -# pre-allocate the buffer to a "worst case" size determined by calling
|
||||
* #tj3JPEGBufSize(). This should ensure that the buffer never has to be
|
||||
* re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.)
|
||||
* .
|
||||
* If you choose option 1, then `*jpegSize` should be set to the size of your
|
||||
* pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC,
|
||||
* you should always check `*jpegBuf` upon return from this function, as it may
|
||||
* have changed.
|
||||
*
|
||||
* @param align row alignment (in bytes) of the YUV image (must be a power of
|
||||
* 2.) Setting this parameter to n will cause each row in each plane of the
|
||||
* YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)
|
||||
* To generate images suitable for X Video, `align` should be set to 4.
|
||||
* @param jpegSize pointer to a size_t variable that holds the size of the JPEG
|
||||
* 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.) If `*jpegBuf` points to a
|
||||
* JPEG buffer that is being reused from a previous call to one of the JPEG
|
||||
* compression functions, then `*jpegSize` is ignored.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3EncodeYUV8(tjhandle handle, const unsigned char *srcBuf,
|
||||
DLLEXPORT int tj3Compress8(tjhandle handle, const unsigned char *srcBuf,
|
||||
int width, int pitch, int height, int pixelFormat,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
/**
|
||||
* Compress a 12-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into
|
||||
* a 12-bit-per-sample JPEG image.
|
||||
*
|
||||
* \details \copydetails tj3Compress8()
|
||||
*/
|
||||
DLLEXPORT int tj3Compress12(tjhandle handle, const short *srcBuf, int width,
|
||||
int pitch, int height, int pixelFormat,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
/**
|
||||
* Compress a 16-bit-per-sample packed-pixel RGB, grayscale, or CMYK image into
|
||||
* a 16-bit-per-sample lossless JPEG image.
|
||||
*
|
||||
* \details \copydetails tj3Compress8()
|
||||
*/
|
||||
DLLEXPORT int tj3Compress16(tjhandle handle, const unsigned short *srcBuf,
|
||||
int width, int pitch, int height, int pixelFormat,
|
||||
unsigned char *dstBuf, int align);
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
|
||||
/**
|
||||
* Compress a set of 8-bit-per-sample Y, U (Cb), and V (Cr) image planes into
|
||||
* an 8-bit-per-sample JPEG image.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
*
|
||||
* @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes
|
||||
* (or just a Y plane, if compressing a grayscale image) that contain a YUV
|
||||
* source image to be compressed. These planes can be contiguous or
|
||||
* non-contiguous in memory. The size of each plane should match the value
|
||||
* returned by #tj3YUVPlaneSize() for the given image width, height, strides,
|
||||
* and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) Refer to
|
||||
* @ref YUVnotes "YUV Image Format Notes" for more details.
|
||||
*
|
||||
* @param width width (in pixels) of the source image. If the width is not an
|
||||
* even multiple of the iMCU width (see #tjMCUWidth), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param strides an array of integers, each specifying the number of bytes per
|
||||
* row in the corresponding plane of the YUV source image. Setting the stride
|
||||
* for any plane to 0 is the same as setting it to the plane width (see
|
||||
* @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the
|
||||
* strides for all planes will be set to their respective plane widths. You
|
||||
* can adjust the strides in order to specify an arbitrary amount of row
|
||||
* padding in each plane or to create a JPEG image from a subregion of a larger
|
||||
* planar YUV image.
|
||||
*
|
||||
* @param height height (in pixels) of the source image. If the height is not
|
||||
* an even multiple of the iMCU height (see #tjMCUHeight), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param jpegBuf address of a pointer to a byte 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 #tj3Alloc() and
|
||||
* let TurboJPEG grow the buffer as needed,
|
||||
* -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you,
|
||||
* or
|
||||
* -# pre-allocate the buffer to a "worst case" size determined by calling
|
||||
* #tj3JPEGBufSize(). This should ensure that the buffer never has to be
|
||||
* re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.)
|
||||
* .
|
||||
* If you choose option 1, then `*jpegSize` should be set to the size of your
|
||||
* pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC,
|
||||
* you should always check `*jpegBuf` upon return from this function, as it may
|
||||
* have changed.
|
||||
*
|
||||
* @param jpegSize pointer to a size_t variable that holds the size of the JPEG
|
||||
* 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.) If `*jpegBuf` points to a
|
||||
* JPEG buffer that is being reused from a previous call to one of the JPEG
|
||||
* compression functions, then `*jpegSize` is ignored.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3CompressFromYUVPlanes8(tjhandle handle,
|
||||
const unsigned char * const *srcPlanes,
|
||||
int width, const int *strides,
|
||||
int height, unsigned char **jpegBuf,
|
||||
size_t *jpegSize);
|
||||
|
||||
|
||||
/**
|
||||
* Compress an 8-bit-per-sample unified planar YUV image into an
|
||||
* 8-bit-per-sample JPEG image.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a unified planar YUV source
|
||||
* image to be compressed. The size of this buffer should match the value
|
||||
* returned by #tj3YUVBufSize() for the given image width, height, row
|
||||
* alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The
|
||||
* Y, U (Cb), and V (Cr) image planes should be stored sequentially in the
|
||||
* buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".)
|
||||
*
|
||||
* @param width width (in pixels) of the source image. If the width is not an
|
||||
* even multiple of the iMCU width (see #tjMCUWidth), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param align row alignment (in bytes) of the source image (must be a power
|
||||
* of 2.) Setting this parameter to n indicates that each row in each plane of
|
||||
* the source image is padded to the nearest multiple of n bytes
|
||||
* (1 = unpadded.)
|
||||
*
|
||||
* @param height height (in pixels) of the source image. If the height is not
|
||||
* an even multiple of the iMCU height (see #tjMCUHeight), then an intermediate
|
||||
* buffer copy will be performed.
|
||||
*
|
||||
* @param jpegBuf address of a pointer to a byte 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 #tj3Alloc() and
|
||||
* let TurboJPEG grow the buffer as needed,
|
||||
* -# set `*jpegBuf` to NULL to tell TurboJPEG to allocate the buffer for you,
|
||||
* or
|
||||
* -# pre-allocate the buffer to a "worst case" size determined by calling
|
||||
* #tj3JPEGBufSize(). This should ensure that the buffer never has to be
|
||||
* re-allocated. (Setting #TJPARAM_NOREALLOC guarantees that it won't be.)
|
||||
* .
|
||||
* If you choose option 1, then `*jpegSize` should be set to the size of your
|
||||
* pre-allocated buffer. In any case, unless you have set #TJPARAM_NOREALLOC,
|
||||
* you should always check `*jpegBuf` upon return from this function, as it may
|
||||
* have changed.
|
||||
*
|
||||
* @param jpegSize pointer to a size_t variable that holds the size of the JPEG
|
||||
* 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.) If `*jpegBuf` points to a
|
||||
* JPEG buffer that is being reused from a previous call to one of the JPEG
|
||||
* compression functions, then `*jpegSize` is ignored.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3CompressFromYUV8(tjhandle handle,
|
||||
const unsigned char *srcBuf, int width,
|
||||
int align, int height,
|
||||
unsigned char **jpegBuf, size_t *jpegSize);
|
||||
|
||||
|
||||
/**
|
||||
@@ -1624,6 +1640,54 @@ DLLEXPORT int tj3EncodeYUVPlanes8(tjhandle handle, const unsigned char *srcBuf,
|
||||
int *strides);
|
||||
|
||||
|
||||
/**
|
||||
* Encode an 8-bit-per-sample packed-pixel RGB or grayscale image into an
|
||||
* 8-bit-per-sample unified planar YUV image. This function performs color
|
||||
* conversion (which is accelerated in the libjpeg-turbo implementation) but
|
||||
* does not execute any of the other steps in the JPEG compression process.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* compression
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a packed-pixel RGB or grayscale
|
||||
* source image to be encoded. This buffer should normally be `pitch * height`
|
||||
* bytes in size. However, you can also use this parameter to encode from a
|
||||
* specific region of a larger buffer.
|
||||
*
|
||||
* @param width width (in pixels) of the source image
|
||||
*
|
||||
* @param pitch bytes per row in the source image. Normally this should be
|
||||
* <tt>width * #tjPixelSize[pixelFormat]</tt>, if the image is unpadded.
|
||||
* (Setting this parameter to 0 is the equivalent of setting it to
|
||||
* <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can also use this
|
||||
* parameter to specify the row alignment/padding of the source image, to skip
|
||||
* rows, or to encode from a specific region of a larger packed-pixel image.
|
||||
*
|
||||
* @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 a buffer that will receive the unified planar YUV
|
||||
* image. Use #tj3YUVBufSize() to determine the appropriate size for this
|
||||
* buffer based on the image width, height, row alignment, and level of
|
||||
* chrominance subsampling (see #TJPARAM_SUBSAMP.) The Y, U (Cb), and V (Cr)
|
||||
* image planes will be stored sequentially in the buffer. (Refer to
|
||||
* @ref YUVnotes "YUV Image Format Notes".)
|
||||
*
|
||||
* @param align row alignment (in bytes) of the YUV image (must be a power of
|
||||
* 2.) Setting this parameter to n will cause each row in each plane of the
|
||||
* YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)
|
||||
* To generate images suitable for X Video, `align` should be set to 4.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3EncodeYUV8(tjhandle handle, const unsigned char *srcBuf,
|
||||
int width, int pitch, int height, int pixelFormat,
|
||||
unsigned char *dstBuf, int align);
|
||||
|
||||
|
||||
/**
|
||||
* Retrieve information about a JPEG image without decompressing it, or prime
|
||||
* the decompressor with quantization and Huffman tables. If a JPEG image is
|
||||
@@ -1782,43 +1846,6 @@ DLLEXPORT int tj3Decompress16(tjhandle handle, const unsigned char *jpegBuf,
|
||||
int pitch, int pixelFormat);
|
||||
|
||||
|
||||
/**
|
||||
* Decompress an 8-bit-per-sample JPEG image into an 8-bit-per-sample unified
|
||||
* planar YUV image. This function performs JPEG decompression but leaves out
|
||||
* the color conversion step, so a planar YUV image is generated instead of a
|
||||
* packed-pixel image. The @ref TJPARAM "parameters" that describe the JPEG
|
||||
* image will be set when this function returns.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* decompression
|
||||
*
|
||||
* @param jpegBuf pointer to a byte buffer containing the JPEG image to
|
||||
* decompress
|
||||
*
|
||||
* @param jpegSize size of the JPEG image (in bytes)
|
||||
*
|
||||
* @param dstBuf pointer to a buffer that will receive the unified planar YUV
|
||||
* decompressed image. Use #tj3YUVBufSize() to determine the appropriate size
|
||||
* for this buffer based on the scaled JPEG width and height (see #TJSCALED(),
|
||||
* #TJPARAM_JPEGWIDTH, #TJPARAM_JPEGHEIGHT, and #tj3SetScalingFactor()), row
|
||||
* alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The
|
||||
* Y, U (Cb), and V (Cr) image planes will be stored sequentially in the
|
||||
* buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".)
|
||||
*
|
||||
* @param align row alignment (in bytes) of the YUV image (must be a power of
|
||||
* 2.) Setting this parameter to n will cause each row in each plane of the
|
||||
* YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)
|
||||
* To generate images suitable for X Video, `align` should be set to 4.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3DecompressToYUV8(tjhandle handle,
|
||||
const unsigned char *jpegBuf,
|
||||
size_t jpegSize,
|
||||
unsigned char *dstBuf, int align);
|
||||
|
||||
|
||||
/**
|
||||
* Decompress an 8-bit-per-sample JPEG image into separate 8-bit-per-sample Y,
|
||||
* U (Cb), and V (Cr) image planes. This function performs JPEG decompression
|
||||
@@ -1863,52 +1890,40 @@ DLLEXPORT int tj3DecompressToYUVPlanes8(tjhandle handle,
|
||||
|
||||
|
||||
/**
|
||||
* Decode an 8-bit-per-sample unified planar YUV image into an 8-bit-per-sample
|
||||
* packed-pixel RGB or grayscale image. This function performs color
|
||||
* conversion (which is accelerated in the libjpeg-turbo implementation) but
|
||||
* does not execute any of the other steps in the JPEG decompression process.
|
||||
* Decompress an 8-bit-per-sample JPEG image into an 8-bit-per-sample unified
|
||||
* planar YUV image. This function performs JPEG decompression but leaves out
|
||||
* the color conversion step, so a planar YUV image is generated instead of a
|
||||
* packed-pixel image. The @ref TJPARAM "parameters" that describe the JPEG
|
||||
* image will be set when this function returns.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* decompression
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a unified planar YUV source
|
||||
* image to be decoded. The size of this buffer should match the value
|
||||
* returned by #tj3YUVBufSize() for the given image width, height, row
|
||||
* @param jpegBuf pointer to a byte buffer containing the JPEG image to
|
||||
* decompress
|
||||
*
|
||||
* @param jpegSize size of the JPEG image (in bytes)
|
||||
*
|
||||
* @param dstBuf pointer to a buffer that will receive the unified planar YUV
|
||||
* decompressed image. Use #tj3YUVBufSize() to determine the appropriate size
|
||||
* for this buffer based on the scaled JPEG width and height (see #TJSCALED(),
|
||||
* #TJPARAM_JPEGWIDTH, #TJPARAM_JPEGHEIGHT, and #tj3SetScalingFactor()), row
|
||||
* alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The
|
||||
* Y, U (Cb), and V (Cr) image planes should be stored sequentially in the
|
||||
* source buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".)
|
||||
* Y, U (Cb), and V (Cr) image planes will be stored sequentially in the
|
||||
* buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".)
|
||||
*
|
||||
* @param align row alignment (in bytes) of the YUV source image (must be a
|
||||
* power of 2.) Setting this parameter to n indicates that each row in each
|
||||
* plane of the YUV source image is padded to the nearest multiple of n bytes
|
||||
* (1 = unpadded.)
|
||||
*
|
||||
* @param dstBuf pointer to a buffer that will receive the packed-pixel decoded
|
||||
* image. This buffer should normally be `pitch * height` bytes in size.
|
||||
* However, you can also use this parameter to decode into a specific region of
|
||||
* a larger buffer.
|
||||
*
|
||||
* @param width width (in pixels) of the source and destination images
|
||||
*
|
||||
* @param pitch bytes per row in the destination image. Normally this should
|
||||
* be set to <tt>width * #tjPixelSize[pixelFormat]</tt>, if the destination
|
||||
* image should be unpadded. (Setting this parameter to 0 is the equivalent of
|
||||
* setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can
|
||||
* also use this parameter to specify the row alignment/padding of the
|
||||
* destination image, to skip rows, or to decode into a specific region of a
|
||||
* larger buffer.
|
||||
*
|
||||
* @param height height (in pixels) of the source and destination images
|
||||
*
|
||||
* @param pixelFormat pixel format of the destination image (see @ref TJPF
|
||||
* "Pixel formats".)
|
||||
* @param align row alignment (in bytes) of the YUV image (must be a power of
|
||||
* 2.) Setting this parameter to n will cause each row in each plane of the
|
||||
* YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)
|
||||
* To generate images suitable for X Video, `align` should be set to 4.
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3DecodeYUV8(tjhandle handle, const unsigned char *srcBuf,
|
||||
int align, unsigned char *dstBuf, int width,
|
||||
int pitch, int height, int pixelFormat);
|
||||
DLLEXPORT int tj3DecompressToYUV8(tjhandle handle,
|
||||
const unsigned char *jpegBuf,
|
||||
size_t jpegSize,
|
||||
unsigned char *dstBuf, int align);
|
||||
|
||||
|
||||
/**
|
||||
@@ -1967,6 +1982,55 @@ DLLEXPORT int tj3DecodeYUVPlanes8(tjhandle handle,
|
||||
int pixelFormat);
|
||||
|
||||
|
||||
/**
|
||||
* Decode an 8-bit-per-sample unified planar YUV image into an 8-bit-per-sample
|
||||
* packed-pixel RGB or grayscale image. This function performs color
|
||||
* conversion (which is accelerated in the libjpeg-turbo implementation) but
|
||||
* does not execute any of the other steps in the JPEG decompression process.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance that has been initialized for
|
||||
* decompression
|
||||
*
|
||||
* @param srcBuf pointer to a buffer containing a unified planar YUV source
|
||||
* image to be decoded. The size of this buffer should match the value
|
||||
* returned by #tj3YUVBufSize() for the given image width, height, row
|
||||
* alignment, and level of chrominance subsampling (see #TJPARAM_SUBSAMP.) The
|
||||
* Y, U (Cb), and V (Cr) image planes should be stored sequentially in the
|
||||
* source buffer. (Refer to @ref YUVnotes "YUV Image Format Notes".)
|
||||
*
|
||||
* @param align row alignment (in bytes) of the YUV source image (must be a
|
||||
* power of 2.) Setting this parameter to n indicates that each row in each
|
||||
* plane of the YUV source image is padded to the nearest multiple of n bytes
|
||||
* (1 = unpadded.)
|
||||
*
|
||||
* @param dstBuf pointer to a buffer that will receive the packed-pixel decoded
|
||||
* image. This buffer should normally be `pitch * height` bytes in size.
|
||||
* However, you can also use this parameter to decode into a specific region of
|
||||
* a larger buffer.
|
||||
*
|
||||
* @param width width (in pixels) of the source and destination images
|
||||
*
|
||||
* @param pitch bytes per row in the destination image. Normally this should
|
||||
* be set to <tt>width * #tjPixelSize[pixelFormat]</tt>, if the destination
|
||||
* image should be unpadded. (Setting this parameter to 0 is the equivalent of
|
||||
* setting it to <tt>width * #tjPixelSize[pixelFormat]</tt>.) However, you can
|
||||
* also use this parameter to specify the row alignment/padding of the
|
||||
* destination image, to skip rows, or to decode into a specific region of a
|
||||
* larger buffer.
|
||||
*
|
||||
* @param height height (in pixels) of the source and destination images
|
||||
*
|
||||
* @param pixelFormat pixel format of the destination image (see @ref TJPF
|
||||
* "Pixel formats".)
|
||||
*
|
||||
* @return 0 if successful, or -1 if an error occurred (see #tj3GetErrorStr()
|
||||
* and #tj3GetErrorCode().)
|
||||
*/
|
||||
DLLEXPORT int tj3DecodeYUV8(tjhandle handle, const unsigned char *srcBuf,
|
||||
int align, unsigned char *dstBuf, int width,
|
||||
int pitch, int height, int pixelFormat);
|
||||
|
||||
|
||||
/**
|
||||
* Losslessly transform a JPEG image into another JPEG image. Lossless
|
||||
* transforms work by moving the raw DCT coefficients from one JPEG image
|
||||
@@ -2032,31 +2096,6 @@ DLLEXPORT int tj3Transform(tjhandle handle, const unsigned char *jpegBuf,
|
||||
size_t *dstSizes, const tjtransform *transforms);
|
||||
|
||||
|
||||
/**
|
||||
* Destroy a TurboJPEG instance.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance. If the handle is NULL, then
|
||||
* this function has no effect.
|
||||
*/
|
||||
DLLEXPORT void tj3Destroy(tjhandle handle);
|
||||
|
||||
|
||||
/**
|
||||
* Allocate a byte buffer for use with TurboJPEG. You should always use this
|
||||
* function to allocate the JPEG destination buffer(s) for the compression and
|
||||
* transform functions unless you are disabling automatic buffer (re)allocation
|
||||
* (by setting #TJPARAM_NOREALLOC.)
|
||||
*
|
||||
* @param bytes the number of bytes to allocate
|
||||
*
|
||||
* @return a pointer to a newly-allocated buffer with the specified number of
|
||||
* bytes.
|
||||
*
|
||||
* @see tj3Free()
|
||||
*/
|
||||
DLLEXPORT void *tj3Alloc(size_t bytes);
|
||||
|
||||
|
||||
/**
|
||||
* Load an 8-bit-per-sample packed-pixel image from disk into memory.
|
||||
*
|
||||
@@ -2180,45 +2219,6 @@ DLLEXPORT int tj3SaveImage16(tjhandle handle, const char *filename,
|
||||
int pitch, int height, int pixelFormat);
|
||||
|
||||
|
||||
/**
|
||||
* Free a byte buffer previously allocated by TurboJPEG. You should always use
|
||||
* this function to free JPEG destination buffer(s) that were automatically
|
||||
* (re)allocated by the compression and transform functions or that were
|
||||
* manually allocated using #tj3Alloc().
|
||||
*
|
||||
* @param buffer address of the buffer to free. If the address is NULL, then
|
||||
* this function has no effect.
|
||||
*
|
||||
* @see tj3Alloc()
|
||||
*/
|
||||
DLLEXPORT void tj3Free(void *buffer);
|
||||
|
||||
|
||||
/**
|
||||
* Returns a descriptive error message explaining why the last command failed.
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance, or NULL if the error was
|
||||
* generated by a global function (but note that retrieving the error message
|
||||
* for a global function is thread-safe only on platforms that support
|
||||
* thread-local storage.)
|
||||
*
|
||||
* @return a descriptive error message explaining why the last command failed.
|
||||
*/
|
||||
DLLEXPORT char *tj3GetErrorStr(tjhandle handle);
|
||||
|
||||
|
||||
/**
|
||||
* Returns a code indicating the severity of the last error. See
|
||||
* @ref TJERR "Error codes".
|
||||
*
|
||||
* @param handle handle to a TurboJPEG instance
|
||||
*
|
||||
* @return a code indicating the severity of the last error. See
|
||||
* @ref TJERR "Error codes".
|
||||
*/
|
||||
DLLEXPORT int tj3GetErrorCode(tjhandle handle);
|
||||
|
||||
|
||||
/* Backward compatibility functions and macros (nothing to see here) */
|
||||
|
||||
/* TurboJPEG 1.0+ */
|
||||
|
||||
Reference in New Issue
Block a user