ryan/mozjpeg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TurboJPEG: Numerous documentation improvements

Browse Source 
- Wordsmithing, formatting, and grammar tweaks

- Various clarifications and corrections, including specifying whether
  a particular buffer or image is used as a source or destination

- Accommodate/mention features that were introduced since the API
  documentation was created.

- For clarity, use "packed-pixel" to describe uncompressed
  source/destination images that are not planar YUV.

- Use "row" rather than "line" to refer to a single horizontal group of
  pixels or component values, for consistency with the libjpeg API
  documentation.  (libjpeg also uses "scanline", which is a more archaic
  term.)

- Use "alignment" rather than "padding" to refer to the number of bytes
  by which a row's width is evenly divisible.  This consistifies the
  documention of the YUV functions and tjLoadImage().  ("Padding"
  typically refers to the number of bytes added to each row, which is
  not the same thing.)

- Remove all references to "the underlying codec."  Although the
  TurboJPEG API originated as a cross-platform wrapper for the Intel
  Integrated Performance Primitives, Sun mediaLib, QuickTime, and
  libjpeg, none of those TurboJPEG implementations has been maintained
  since 2009.  Nothing would prevent someone from implementing the
  TurboJPEG API without libjpeg-turbo, but such an implementation would
  not necessarily have an "underlying codec."  (It could be fully
  self-contained.)

- Use "destination image" rather than "output image", for consistency,
  or describe the type of image that will be output.

- Avoid the term "image buffer" and instead use "byte buffer" to
  refer to buffers that will hold JPEG images, or describe the type of
  image that will be contained in the buffer.  (The Java documentation
  doesn't use "byte buffer", because the buffer arrays literally have
  "byte" in front of them, and since Java doesn't have pointers, it is
  not possible for mere mortals to store any other type of data in those
  arrays.)

- C: Use "unified" to describe YUV images stored in a single buffer, for
  consistency with the Java documentation.

- Use "planar YUV" rather than "YUV planar".  Is is our convention to
  describe images using {component layout} {colorspace/pixel format}
  {image function}, e.g. "packed-pixel RGB source image" or "planar YUV
  destination image."

- C: Document the TurboJPEG API version in which a particular function
  or macro was introduced, and reorder the backward compatibility
  function stubs in turbojpeg.h alphabetically by API version.

- C: Use Markdown rather than HTML tags, where possible, in the Doxygen
  comments.
This commit is contained in:
DRC
2023-01-06 10:29:10 -06:00
parent b03ee8b835
commit 9a146f0f23
31 changed files with 1845 additions and 1716 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
turbojpeg.c
View File

@@ -97,7 +97,7 @@ static void my_emit_message(j_common_ptr cinfo, int msg_level)
}
/* Global structures, macros, etc. */
/********************** Global structures, macros, etc. **********************/
enum { COMPRESS = 1, DECOMPRESS = 2 };
@@ -425,8 +425,9 @@ static int getSubsamp(j_decompress_ptr dinfo)
}
/* General API functions */
/*************************** General API functions ***************************/
/* TurboJPEG 2.0+ */
DLLEXPORT char *tjGetErrorStr2(tjhandle handle)
{
tjinstance *this = (tjinstance *)handle;
@@ -439,12 +440,14 @@ DLLEXPORT char *tjGetErrorStr2(tjhandle handle)
}
/* TurboJPEG 1.0+ */
DLLEXPORT char *tjGetErrorStr(void)
{
return errStr;
}
/* TurboJPEG 2.0+ */
DLLEXPORT int tjGetErrorCode(tjhandle handle)
{
tjinstance *this = (tjinstance *)handle;
@@ -454,6 +457,7 @@ DLLEXPORT int tjGetErrorCode(tjhandle handle)
}
/* TurboJPEG 1.0+ */
DLLEXPORT int tjDestroy(tjhandle handle)
{
GET_INSTANCE(handle);
@@ -471,19 +475,21 @@ DLLEXPORT int tjDestroy(tjhandle handle)
with turbojpeg.dll for compatibility reasons. However, these functions
can potentially be used for other purposes by different implementations. */
/* TurboJPEG 1.2+ */
DLLEXPORT void tjFree(unsigned char *buf)
{
free(buf);
}
/* TurboJPEG 1.2+ */
DLLEXPORT unsigned char *tjAlloc(int bytes)
{
return (unsigned char *)malloc(bytes);
}
/* Compressor */
/******************************** Compressor *********************************/
static tjhandle _tjInitCompress(tjinstance *this)
{
@@ -515,6 +521,7 @@ static tjhandle _tjInitCompress(tjinstance *this)
return (tjhandle)this;
}
/* TurboJPEG 1.0+ */
DLLEXPORT tjhandle tjInitCompress(void)
{
tjinstance *this = NULL;
@@ -530,6 +537,7 @@ DLLEXPORT tjhandle tjInitCompress(void)
}
/* TurboJPEG 1.2+ */
DLLEXPORT unsigned long tjBufSize(int width, int height, int jpegSubsamp)
{
unsigned long long retval = 0;
@@ -552,6 +560,7 @@ bailout:
return (unsigned long)retval;
}
/* TurboJPEG 1.0+ */
DLLEXPORT unsigned long TJBUFSIZE(int width, int height)
{
unsigned long long retval = 0;
@@ -571,19 +580,20 @@ bailout:
}
DLLEXPORT unsigned long tjBufSizeYUV2(int width, int pad, int height,
/* TurboJPEG 1.4+ */
DLLEXPORT unsigned long tjBufSizeYUV2(int width, int align, int height,
int subsamp)
{
unsigned long long retval = 0;
int nc, i;
if (pad < 1 || !IS_POW2(pad) || subsamp < 0 || subsamp >= TJ_NUMSAMP)
if (align < 1 || !IS_POW2(align) || subsamp < 0 || subsamp >= TJ_NUMSAMP)
THROWG("tjBufSizeYUV2(): Invalid argument");
nc = (subsamp == TJSAMP_GRAY ? 1 : 3);
for (i = 0; i < nc; i++) {
int pw = tjPlaneWidth(i, width, subsamp);
int stride = PAD(pw, pad);
int stride = PAD(pw, align);
int ph = tjPlaneHeight(i, height, subsamp);
if (pw < 0 || ph < 0) return -1;
@@ -596,17 +606,20 @@ bailout:
return (unsigned long)retval;
}
/* TurboJPEG 1.2+ */
DLLEXPORT unsigned long tjBufSizeYUV(int width, int height, int subsamp)
{
return tjBufSizeYUV2(width, 4, height, subsamp);
}
/* TurboJPEG 1.1+ */
DLLEXPORT unsigned long TJBUFSIZEYUV(int width, int height, int subsamp)
{
return tjBufSizeYUV(width, height, subsamp);
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjPlaneWidth(int componentID, int width, int subsamp)
{
int pw, nc, retval = 0;
@@ -628,6 +641,7 @@ bailout:
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjPlaneHeight(int componentID, int height, int subsamp)
{
int ph, nc, retval = 0;
@@ -649,6 +663,7 @@ bailout:
}
/* TurboJPEG 1.4+ */
DLLEXPORT unsigned long tjPlaneSizeYUV(int componentID, int width, int stride,
int height, int subsamp)
{
@@ -674,6 +689,7 @@ bailout:
}
/* TurboJPEG 1.2+ */
DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf,
int width, int pitch, int height, int pixelFormat,
unsigned char **jpegBuf, unsigned long *jpegSize,
@@ -742,6 +758,7 @@ bailout:
return retval;
}
/* TurboJPEG 1.0+ */
DLLEXPORT int tjCompress(tjhandle handle, unsigned char *srcBuf, int width,
int pitch, int height, int pixelSize,
unsigned char *jpegBuf, unsigned long *jpegSize,
@@ -765,6 +782,7 @@ DLLEXPORT int tjCompress(tjhandle handle, unsigned char *srcBuf, int width,
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf,
int width, int pitch, int height,
int pixelFormat, unsigned char **dstPlanes,
@@ -797,7 +815,7 @@ DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf,
THROW("tjEncodeYUVPlanes(): Invalid argument");
if (pixelFormat == TJPF_CMYK)
THROW("tjEncodeYUVPlanes(): Cannot generate YUV images from CMYK pixels");
THROW("tjEncodeYUVPlanes(): Cannot generate YUV images from packed-pixel CMYK images");
if (pitch == 0) pitch = width * tjPixelSize[pixelFormat];
@@ -923,9 +941,10 @@ bailout:
return retval;
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf,
int width, int pitch, int height, int pixelFormat,
unsigned char *dstBuf, int pad, int subsamp,
unsigned char *dstBuf, int align, int subsamp,
int flags)
{
unsigned char *dstPlanes[3];
@@ -935,14 +954,14 @@ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf,
if (!this) THROWG("tjEncodeYUV3(): Invalid handle");
this->isInstanceError = FALSE;
if (width <= 0 || height <= 0 || dstBuf == NULL || pad < 1 ||
!IS_POW2(pad) || subsamp < 0 || subsamp >= TJ_NUMSAMP)
if (width <= 0 || height <= 0 || dstBuf == NULL || align < 1 ||
!IS_POW2(align) || subsamp < 0 || subsamp >= TJ_NUMSAMP)
THROW("tjEncodeYUV3(): Invalid argument");
pw0 = tjPlaneWidth(0, width, subsamp);
ph0 = tjPlaneHeight(0, height, subsamp);
dstPlanes[0] = dstBuf;
strides[0] = PAD(pw0, pad);
strides[0] = PAD(pw0, align);
if (subsamp == TJSAMP_GRAY) {
strides[1] = strides[2] = 0;
dstPlanes[1] = dstPlanes[2] = NULL;
@@ -950,7 +969,7 @@ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf,
int pw1 = tjPlaneWidth(1, width, subsamp);
int ph1 = tjPlaneHeight(1, height, subsamp);
strides[1] = strides[2] = PAD(pw1, pad);
strides[1] = strides[2] = PAD(pw1, align);
dstPlanes[1] = dstPlanes[0] + strides[0] * ph0;
dstPlanes[2] = dstPlanes[1] + strides[1] * ph1;
}
@@ -962,6 +981,7 @@ bailout:
return retval;
}
/* TurboJPEG 1.2+ */
DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width,
int pitch, int height, int pixelFormat,
unsigned char *dstBuf, int subsamp, int flags)
@@ -970,6 +990,7 @@ DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width,
dstBuf, 4, subsamp, flags);
}
/* TurboJPEG 1.1+ */
DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width,
int pitch, int height, int pixelSize,
unsigned char *dstBuf, int subsamp, int flags)
@@ -980,6 +1001,7 @@ DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width,
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle,
const unsigned char **srcPlanes,
int width, const int *strides,
@@ -1118,8 +1140,9 @@ bailout:
return retval;
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf,
int width, int pad, int height, int subsamp,
int width, int align, int height, int subsamp,
unsigned char **jpegBuf,
unsigned long *jpegSize, int jpegQual,
int flags)
@@ -1131,14 +1154,14 @@ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf,
if (!this) THROWG("tjCompressFromYUV(): Invalid handle");
this->isInstanceError = FALSE;
if (srcBuf == NULL || width <= 0 || pad < 1 || !IS_POW2(pad) ||
if (srcBuf == NULL || width <= 0 || align < 1 || !IS_POW2(align) ||
height <= 0 || subsamp < 0 || subsamp >= TJ_NUMSAMP)
THROW("tjCompressFromYUV(): Invalid argument");
pw0 = tjPlaneWidth(0, width, subsamp);
ph0 = tjPlaneHeight(0, height, subsamp);
srcPlanes[0] = srcBuf;
strides[0] = PAD(pw0, pad);
strides[0] = PAD(pw0, align);
if (subsamp == TJSAMP_GRAY) {
strides[1] = strides[2] = 0;
srcPlanes[1] = srcPlanes[2] = NULL;
@@ -1146,7 +1169,7 @@ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf,
int pw1 = tjPlaneWidth(1, width, subsamp);
int ph1 = tjPlaneHeight(1, height, subsamp);
strides[1] = strides[2] = PAD(pw1, pad);
strides[1] = strides[2] = PAD(pw1, align);
srcPlanes[1] = srcPlanes[0] + strides[0] * ph0;
srcPlanes[2] = srcPlanes[1] + strides[1] * ph1;
}
@@ -1159,7 +1182,7 @@ bailout:
}
/* Decompressor */
/******************************* Decompressor ********************************/
static tjhandle _tjInitDecompress(tjinstance *this)
{
@@ -1189,6 +1212,7 @@ static tjhandle _tjInitDecompress(tjinstance *this)
return (tjhandle)this;
}
/* TurboJPEG 1.0+ */
DLLEXPORT tjhandle tjInitDecompress(void)
{
tjinstance *this;
@@ -1204,6 +1228,7 @@ DLLEXPORT tjhandle tjInitDecompress(void)
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjDecompressHeader3(tjhandle handle,
const unsigned char *jpegBuf,
unsigned long jpegSize, int *width,
@@ -1260,6 +1285,7 @@ bailout:
return retval;
}
/* TurboJPEG 1.1+ */
DLLEXPORT int tjDecompressHeader2(tjhandle handle, unsigned char *jpegBuf,
unsigned long jpegSize, int *width,
int *height, int *jpegSubsamp)
@@ -1270,6 +1296,7 @@ DLLEXPORT int tjDecompressHeader2(tjhandle handle, unsigned char *jpegBuf,
jpegSubsamp, &jpegColorspace);
}
/* TurboJPEG 1.0+ */
DLLEXPORT int tjDecompressHeader(tjhandle handle, unsigned char *jpegBuf,
unsigned long jpegSize, int *width,
int *height)
@@ -1281,19 +1308,21 @@ DLLEXPORT int tjDecompressHeader(tjhandle handle, unsigned char *jpegBuf,
}
DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numscalingfactors)
/* TurboJPEG 1.2+ */
DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numScalingFactors)
{
if (numscalingfactors == NULL) {
if (numScalingFactors == NULL) {
SNPRINTF(errStr, JMSG_LENGTH_MAX,
"tjGetScalingFactors(): Invalid argument");
return NULL;
}
*numscalingfactors = NUMSF;
*numScalingFactors = NUMSF;
return (tjscalingfactor *)sf;
}
/* TurboJPEG 1.2+ */
DLLEXPORT int tjDecompress2(tjhandle handle, const unsigned char *jpegBuf,
unsigned long jpegSize, unsigned char *dstBuf,
int width, int pitch, int height, int pixelFormat,
@@ -1381,6 +1410,7 @@ bailout:
return retval;
}
/* TurboJPEG 1.0+ */
DLLEXPORT int tjDecompress(tjhandle handle, unsigned char *jpegBuf,
unsigned long jpegSize, unsigned char *dstBuf,
int width, int pitch, int height, int pixelSize,
@@ -1442,6 +1472,7 @@ static void my_reset_marker_reader(j_decompress_ptr dinfo)
{
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle,
const unsigned char **srcPlanes,
const int *strides, int subsamp,
@@ -1480,7 +1511,7 @@ DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle,
}
if (pixelFormat == TJPF_CMYK)
THROW("tjDecodeYUVPlanes(): Cannot decode YUV images into CMYK pixels.");
THROW("tjDecodeYUVPlanes(): Cannot decode YUV images into packed-pixel CMYK images.");
if (pitch == 0) pitch = width * tjPixelSize[pixelFormat];
dinfo->image_width = width;
@@ -1588,8 +1619,9 @@ bailout:
return retval;
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf,
int pad, int subsamp, unsigned char *dstBuf,
int align, int subsamp, unsigned char *dstBuf,
int width, int pitch, int height, int pixelFormat,
int flags)
{
@@ -1600,14 +1632,14 @@ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf,
if (!this) THROWG("tjDecodeYUV(): Invalid handle");
this->isInstanceError = FALSE;
if (srcBuf == NULL || pad < 1 || !IS_POW2(pad) || subsamp < 0 ||
if (srcBuf == NULL || align < 1 || !IS_POW2(align) || subsamp < 0 ||
subsamp >= TJ_NUMSAMP || width <= 0 || height <= 0)
THROW("tjDecodeYUV(): Invalid argument");
pw0 = tjPlaneWidth(0, width, subsamp);
ph0 = tjPlaneHeight(0, height, subsamp);
srcPlanes[0] = srcBuf;
strides[0] = PAD(pw0, pad);
strides[0] = PAD(pw0, align);
if (subsamp == TJSAMP_GRAY) {
strides[1] = strides[2] = 0;
srcPlanes[1] = srcPlanes[2] = NULL;
@@ -1615,7 +1647,7 @@ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf,
int pw1 = tjPlaneWidth(1, width, subsamp);
int ph1 = tjPlaneHeight(1, height, subsamp);
strides[1] = strides[2] = PAD(pw1, pad);
strides[1] = strides[2] = PAD(pw1, align);
srcPlanes[1] = srcPlanes[0] + strides[0] * ph0;
srcPlanes[2] = srcPlanes[1] + strides[1] * ph1;
}
@@ -1627,6 +1659,7 @@ bailout:
return retval;
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle,
const unsigned char *jpegBuf,
unsigned long jpegSize,
@@ -1807,9 +1840,10 @@ bailout:
return retval;
}
/* TurboJPEG 1.4+ */
DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf,
unsigned long jpegSize, unsigned char *dstBuf,
int width, int pad, int height, int flags)
int width, int align, int height, int flags)
{
unsigned char *dstPlanes[3];
int pw0, ph0, strides[3], retval = -1, jpegSubsamp = -1;
@@ -1819,7 +1853,7 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf,
this->jerr.stopOnWarning = (flags & TJFLAG_STOPONWARNING) ? TRUE : FALSE;
if (jpegBuf == NULL || jpegSize <= 0 || dstBuf == NULL || width < 0 ||
pad < 1 || !IS_POW2(pad) || height < 0)
align < 1 || !IS_POW2(align) || height < 0)
THROW("tjDecompressToYUV2(): Invalid argument");
if (setjmp(this->jerr.setjmp_buffer)) {
@@ -1836,7 +1870,6 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf,
jpegwidth = dinfo->image_width; jpegheight = dinfo->image_height;
if (width == 0) width = jpegwidth;
if (height == 0) height = jpegheight;
for (i = 0; i < NUMSF; i++) {
scaledw = TJSCALED(jpegwidth, sf[i]);
scaledh = TJSCALED(jpegheight, sf[i]);
@@ -1849,7 +1882,7 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf,
pw0 = tjPlaneWidth(0, width, jpegSubsamp);
ph0 = tjPlaneHeight(0, height, jpegSubsamp);
dstPlanes[0] = dstBuf;
strides[0] = PAD(pw0, pad);
strides[0] = PAD(pw0, align);
if (jpegSubsamp == TJSAMP_GRAY) {
strides[1] = strides[2] = 0;
dstPlanes[1] = dstPlanes[2] = NULL;
@@ -1857,7 +1890,7 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf,
int pw1 = tjPlaneWidth(1, width, jpegSubsamp);
int ph1 = tjPlaneHeight(1, height, jpegSubsamp);
strides[1] = strides[2] = PAD(pw1, pad);
strides[1] = strides[2] = PAD(pw1, align);
dstPlanes[1] = dstPlanes[0] + strides[0] * ph0;
dstPlanes[2] = dstPlanes[1] + strides[1] * ph1;
}
@@ -1871,6 +1904,7 @@ bailout:
return retval;
}
/* TurboJPEG 1.1+ */
DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf,
unsigned long jpegSize, unsigned char *dstBuf,
int flags)
@@ -1879,8 +1913,9 @@ DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf,
}
/* Transformer */
/******************************** Transformer ********************************/
/* TurboJPEG 1.2+ */
DLLEXPORT tjhandle tjInitTransform(void)
{
tjinstance *this = NULL;
@@ -1900,6 +1935,7 @@ DLLEXPORT tjhandle tjInitTransform(void)
}
/* TurboJPEG 1.2+ */
DLLEXPORT int tjTransform(tjhandle handle, const unsigned char *jpegBuf,
unsigned long jpegSize, int n,
unsigned char **dstBufs, unsigned long *dstSizes,
@@ -2068,6 +2104,9 @@ bailout:
}
/*************************** Packed-Pixel Image I/O **************************/
/* TurboJPEG 2.0+ */
DLLEXPORT unsigned char *tjLoadImage(const char *filename, int *width,
int align, int *height, int *pixelFormat,
int flags)
@@ -2170,6 +2209,7 @@ bailout:
}
/* TurboJPEG 2.0+ */
DLLEXPORT int tjSaveImage(const char *filename, unsigned char *buffer,
int width, int pitch, int height, int pixelFormat,
int flags)