TurboJPEG: Numerous documentation improvements
- 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
36
tjunittest.c
36
tjunittest.c
@@ -57,7 +57,7 @@ static void usage(char *progName)
|
||||
printf("Options:\n");
|
||||
printf("-yuv = test YUV encoding/decoding support\n");
|
||||
printf("-noyuvpad = do not pad each line of each Y, U, and V plane to the nearest\n");
|
||||
printf(" 4-byte boundary\n");
|
||||
printf(" multiple of 4 bytes\n");
|
||||
printf("-alloc = test automatic buffer allocation\n");
|
||||
printf("-bmp = tjLoadImage()/tjSaveImage() unit test\n\n");
|
||||
exit(1);
|
||||
@@ -95,7 +95,7 @@ const int _4byteFormats[] = {
|
||||
const int _onlyGray[] = { TJPF_GRAY };
|
||||
const int _onlyRGB[] = { TJPF_RGB };
|
||||
|
||||
int doYUV = 0, alloc = 0, pad = 4;
|
||||
int doYUV = 0, alloc = 0, yuvAlign = 4;
|
||||
|
||||
int exitStatus = 0;
|
||||
#define BAILOUT() { exitStatus = -1; goto bailout; }
|
||||
@@ -282,7 +282,7 @@ static int checkBufYUV(unsigned char *buf, int w, int h, int subsamp,
|
||||
int hsf = tjMCUWidth[subsamp] / 8, vsf = tjMCUHeight[subsamp] / 8;
|
||||
int pw = PAD(w, hsf), ph = PAD(h, vsf);
|
||||
int cw = pw / hsf, ch = ph / vsf;
|
||||
int ypitch = PAD(pw, pad), uvpitch = PAD(cw, pad);
|
||||
int ypitch = PAD(pw, yuvAlign), uvpitch = PAD(cw, yuvAlign);
|
||||
int retval = 1;
|
||||
int halfway = 16 * sf.num / sf.denom;
|
||||
int blocksize = 8 * sf.num / sf.denom;
|
||||
@@ -381,7 +381,7 @@ static void compTest(tjhandle handle, unsigned char **dstBuf,
|
||||
|
||||
if (!alloc) flags |= TJFLAG_NOREALLOC;
|
||||
if (doYUV) {
|
||||
unsigned long yuvSize = tjBufSizeYUV2(w, pad, h, subsamp);
|
||||
unsigned long yuvSize = tjBufSizeYUV2(w, yuvAlign, h, subsamp);
|
||||
tjscalingfactor sf = { 1, 1 };
|
||||
tjhandle handle2 = tjInitCompress();
|
||||
|
||||
@@ -392,15 +392,15 @@ static void compTest(tjhandle handle, unsigned char **dstBuf,
|
||||
memset(yuvBuf, 0, yuvSize);
|
||||
|
||||
printf("%s %s -> YUV %s ... ", pfStr, buStrLong, subNameLong[subsamp]);
|
||||
TRY_TJ(tjEncodeYUV3(handle2, srcBuf, w, 0, h, pf, yuvBuf, pad, subsamp,
|
||||
flags));
|
||||
TRY_TJ(tjEncodeYUV3(handle2, srcBuf, w, 0, h, pf, yuvBuf, yuvAlign,
|
||||
subsamp, flags));
|
||||
tjDestroy(handle2);
|
||||
if (checkBufYUV(yuvBuf, w, h, subsamp, sf)) printf("Passed.\n");
|
||||
else printf("FAILED!\n");
|
||||
|
||||
printf("YUV %s %s -> JPEG Q%d ... ", subNameLong[subsamp], buStrLong,
|
||||
jpegQual);
|
||||
TRY_TJ(tjCompressFromYUV(handle, yuvBuf, w, pad, h, subsamp, dstBuf,
|
||||
TRY_TJ(tjCompressFromYUV(handle, yuvBuf, w, yuvAlign, h, subsamp, dstBuf,
|
||||
dstSize, jpegQual, flags));
|
||||
} else {
|
||||
printf("%s %s -> %s Q%d ... ", pfStr, buStrLong, subNameLong[subsamp],
|
||||
@@ -442,7 +442,7 @@ static void _decompTest(tjhandle handle, unsigned char *jpegBuf,
|
||||
memset(dstBuf, 0, dstSize);
|
||||
|
||||
if (doYUV) {
|
||||
unsigned long yuvSize = tjBufSizeYUV2(scaledWidth, pad, scaledHeight,
|
||||
unsigned long yuvSize = tjBufSizeYUV2(scaledWidth, yuvAlign, scaledHeight,
|
||||
subsamp);
|
||||
tjhandle handle2 = tjInitDecompress();
|
||||
|
||||
@@ -457,15 +457,15 @@ static void _decompTest(tjhandle handle, unsigned char *jpegBuf,
|
||||
printf("%d/%d ... ", sf.num, sf.denom);
|
||||
else printf("... ");
|
||||
TRY_TJ(tjDecompressToYUV2(handle, jpegBuf, jpegSize, yuvBuf, scaledWidth,
|
||||
pad, scaledHeight, flags));
|
||||
yuvAlign, scaledHeight, flags));
|
||||
if (checkBufYUV(yuvBuf, scaledWidth, scaledHeight, subsamp, sf))
|
||||
printf("Passed.\n");
|
||||
else printf("FAILED!\n");
|
||||
|
||||
printf("YUV %s -> %s %s ... ", subNameLong[subsamp], pixFormatStr[pf],
|
||||
(flags & TJFLAG_BOTTOMUP) ? "Bottom-Up" : "Top-Down ");
|
||||
TRY_TJ(tjDecodeYUV(handle2, yuvBuf, pad, subsamp, dstBuf, scaledWidth, 0,
|
||||
scaledHeight, pf, flags));
|
||||
TRY_TJ(tjDecodeYUV(handle2, yuvBuf, yuvAlign, subsamp, dstBuf, scaledWidth,
|
||||
0, scaledHeight, pf, flags));
|
||||
tjDestroy(handle2);
|
||||
} else {
|
||||
printf("JPEG -> %s %s ", pixFormatStr[pf],
|
||||
@@ -618,7 +618,7 @@ static void bufSizeTest(void)
|
||||
if ((srcBuf = (unsigned char *)malloc(w * h * 4)) == NULL)
|
||||
THROW("Memory allocation failure");
|
||||
if (!alloc || doYUV) {
|
||||
if (doYUV) dstSize = tjBufSizeYUV2(w, pad, h, subsamp);
|
||||
if (doYUV) dstSize = tjBufSizeYUV2(w, yuvAlign, h, subsamp);
|
||||
else dstSize = tjBufSize(w, h, subsamp);
|
||||
if ((dstBuf = (unsigned char *)tjAlloc(dstSize)) == NULL)
|
||||
THROW("Memory allocation failure");
|
||||
@@ -630,8 +630,8 @@ static void bufSizeTest(void)
|
||||
}
|
||||
|
||||
if (doYUV) {
|
||||
TRY_TJ(tjEncodeYUV3(handle, srcBuf, w, 0, h, TJPF_BGRX, dstBuf, pad,
|
||||
subsamp, 0));
|
||||
TRY_TJ(tjEncodeYUV3(handle, srcBuf, w, 0, h, TJPF_BGRX, dstBuf,
|
||||
yuvAlign, subsamp, 0));
|
||||
} else {
|
||||
TRY_TJ(tjCompress2(handle, srcBuf, w, 0, h, TJPF_BGRX, &dstBuf,
|
||||
&dstSize, subsamp, 100,
|
||||
@@ -645,7 +645,7 @@ static void bufSizeTest(void)
|
||||
if ((srcBuf = (unsigned char *)malloc(h * w * 4)) == NULL)
|
||||
THROW("Memory allocation failure");
|
||||
if (!alloc || doYUV) {
|
||||
if (doYUV) dstSize = tjBufSizeYUV2(h, pad, w, subsamp);
|
||||
if (doYUV) dstSize = tjBufSizeYUV2(h, yuvAlign, w, subsamp);
|
||||
else dstSize = tjBufSize(h, w, subsamp);
|
||||
if ((dstBuf = (unsigned char *)tjAlloc(dstSize)) == NULL)
|
||||
THROW("Memory allocation failure");
|
||||
@@ -657,8 +657,8 @@ static void bufSizeTest(void)
|
||||
}
|
||||
|
||||
if (doYUV) {
|
||||
TRY_TJ(tjEncodeYUV3(handle, srcBuf, h, 0, w, TJPF_BGRX, dstBuf, pad,
|
||||
subsamp, 0));
|
||||
TRY_TJ(tjEncodeYUV3(handle, srcBuf, h, 0, w, TJPF_BGRX, dstBuf,
|
||||
yuvAlign, subsamp, 0));
|
||||
} else {
|
||||
TRY_TJ(tjCompress2(handle, srcBuf, h, 0, w, TJPF_BGRX, &dstBuf,
|
||||
&dstSize, subsamp, 100,
|
||||
@@ -902,7 +902,7 @@ int main(int argc, char *argv[])
|
||||
if (argc > 1) {
|
||||
for (i = 1; i < argc; i++) {
|
||||
if (!strcasecmp(argv[i], "-yuv")) doYUV = 1;
|
||||
else if (!strcasecmp(argv[i], "-noyuvpad")) pad = 1;
|
||||
else if (!strcasecmp(argv[i], "-noyuvpad")) yuvAlign = 1;
|
||||
else if (!strcasecmp(argv[i], "-alloc")) alloc = 1;
|
||||
else if (!strcasecmp(argv[i], "-bmp")) return bmpTest();
|
||||
else usage(argv[0]);
|
||||
|
||||
Reference in New Issue
Block a user