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

143
java/org/libjpegturbo/turbojpeg/TJ.java
View File

@@ -1,6 +1,6 @@
/*
* Copyright (C)2011-2013, 2017-2018, 2020-2021 D. R. Commander.
* All Rights Reserved.
* Copyright (C)2011-2013, 2017-2018, 2020-2021, 2023 D. R. Commander.
* All Rights Reserved.
* Copyright (C)2015 Viktor Szathmáry. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -85,7 +85,7 @@ public final class TJ {
* subsampling.
*
* @param subsamp the level of chrominance subsampling (one of
* <code>SAMP_*</code>)
* {@link #SAMP_444 SAMP_*})
*
* @return the MCU block width for the given level of chrominance
* subsampling.
@@ -105,7 +105,7 @@ public final class TJ {
* subsampling.
*
* @param subsamp the level of chrominance subsampling (one of
* <code>SAMP_*</code>)
* {@link #SAMP_444 SAMP_*})
*
* @return the MCU block height for the given level of chrominance
* subsampling.
@@ -205,8 +205,8 @@ public final class TJ {
* vice versa, but the mapping is typically not 1:1 or reversible, nor can it
* be defined with a simple formula. Thus, such a conversion is out of scope
* for a codec library. However, the TurboJPEG API allows for compressing
* CMYK pixels into a YCCK JPEG image (see {@link #CS_YCCK}) and
* decompressing YCCK JPEG images into CMYK pixels.
* packed-pixel CMYK images into YCCK JPEG images (see {@link #CS_YCCK}) and
* decompressing YCCK JPEG images into packed-pixel CMYK images.
*/
public static final int PF_CMYK = 11;
@@ -214,7 +214,7 @@ public final class TJ {
/**
* Returns the pixel size (in bytes) for the given pixel format.
*
* @param pixelFormat the pixel format (one of <code>PF_*</code>)
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the pixel size (in bytes) for the given pixel format.
*/
@@ -235,7 +235,7 @@ public final class TJ {
* then the red component will be
* <code>pixel[TJ.getRedOffset(TJ.PF_BGRX)]</code>.
*
* @param pixelFormat the pixel format (one of <code>PF_*</code>)
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the red offset for the given pixel format, or -1 if the pixel
* format does not have a red component.
@@ -257,7 +257,7 @@ public final class TJ {
* then the green component will be
* <code>pixel[TJ.getGreenOffset(TJ.PF_BGRX)]</code>.
*
* @param pixelFormat the pixel format (one of <code>PF_*</code>)
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the green offset for the given pixel format, or -1 if the pixel
* format does not have a green component.
@@ -279,7 +279,7 @@ public final class TJ {
* then the blue component will be
* <code>pixel[TJ.getBlueOffset(TJ.PF_BGRX)]</code>.
*
* @param pixelFormat the pixel format (one of <code>PF_*</code>)
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the blue offset for the given pixel format, or -1 if the pixel
* format does not have a blue component.
@@ -301,7 +301,7 @@ public final class TJ {
* then the alpha component will be
* <code>pixel[TJ.getAlphaOffset(TJ.PF_BGRA)]</code>.
*
* @param pixelFormat the pixel format (one of <code>PF_*</code>)
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the alpha offset for the given pixel format, or -1 if the pixel
* format does not have a alpha component.
@@ -324,8 +324,9 @@ public final class TJ {
* RGB colorspace. When compressing the JPEG image, the R, G, and B
* components in the source image are reordered into image planes, but no
* colorspace conversion or subsampling is performed. RGB JPEG images can be
* decompressed to any of the extended RGB pixel formats or grayscale, but
* they cannot be decompressed to YUV images.
* decompressed to packed-pixel images with any of the extended RGB or
* grayscale pixel formats, but they cannot be decompressed to planar YUV
* images.
*/
public static final int CS_RGB = 0;
/**
@@ -339,26 +340,28 @@ public final class TJ {
* transformation allowed the same signal to drive both black &amp; white and
* color televisions, but JPEG images use YCbCr primarily because it allows
* the color data to be optionally subsampled for the purposes of reducing
* bandwidth or disk space. YCbCr is the most common JPEG colorspace, and
* YCbCr JPEG images can be compressed from and decompressed to any of the
* extended RGB pixel formats or grayscale, or they can be decompressed to
* YUV planar images.
* network or disk usage. YCbCr is the most common JPEG colorspace, and
* YCbCr JPEG images can be compressed from and decompressed to packed-pixel
* images with any of the extended RGB or grayscale pixel formats. YCbCr
* JPEG images can also be compressed from and decompressed to planar YUV
* images.
*/
@SuppressWarnings("checkstyle:ConstantName")
public static final int CS_YCbCr = 1;
/**
* Grayscale colorspace. The JPEG image retains only the luminance data (Y
* component), and any color data from the source image is discarded.
* Grayscale JPEG images can be compressed from and decompressed to any of
* the extended RGB pixel formats or grayscale, or they can be decompressed
* to YUV planar images.
* Grayscale JPEG images can be compressed from and decompressed to
* packed-pixel images with any of the extended RGB or grayscale pixel
* formats, or they can be compressed from and decompressed to planar YUV
* images.
*/
public static final int CS_GRAY = 2;
/**
* CMYK colorspace. When compressing the JPEG image, the C, M, Y, and K
* components in the source image are reordered into image planes, but no
* colorspace conversion or subsampling is performed. CMYK JPEG images can
* only be decompressed to CMYK pixels.
* only be decompressed to packed-pixel images with the CMYK pixel format.
*/
public static final int CS_CMYK = 3;
/**
@@ -368,14 +371,14 @@ public final class TJ {
* reversibly transformed into YCCK, and as with YCbCr, the chrominance
* components in the YCCK pixels can be subsampled without incurring major
* perceptual loss. YCCK JPEG images can only be compressed from and
* decompressed to CMYK pixels.
* decompressed to packed-pixel images with the CMYK pixel format.
*/
public static final int CS_YCCK = 4;
/**
* The uncompressed source/destination image is stored in bottom-up (Windows,
* OpenGL) order, not top-down (X11) order.
* Rows in the packed-pixel source/destination image are stored in bottom-up
* (Windows, OpenGL) order rather than in top-down (X11) order.
*/
public static final int FLAG_BOTTOMUP = 2;
@@ -394,41 +397,39 @@ public final class TJ {
/**
* 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.
* subsampling, use the fastest chrominance upsampling algorithm available.
* 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.
*/
public static final int FLAG_FASTUPSAMPLE = 256;
/**
* Use the fastest DCT/IDCT algorithm available in the underlying codec. The
* default if this flag is not specified is implementation-specific. For
* example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast
* Use the fastest DCT/IDCT algorithm available. The default if this flag is
* not specified is implementation-specific. For example, the implementation
* of the TurboJPEG API in libjpeg-turbo 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.
*/
public static final int FLAG_FASTDCT = 2048;
/**
* Use the most accurate DCT/IDCT algorithm available. The default if this
* flag is not specified is implementation-specific. For example, the
* implementation of the TurboJPEG API in libjpeg-turbo 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.
*/
public static final int FLAG_FASTDCT = 2048;
/**
* Use the most accurate DCT/IDCT algorithm available in the underlying
* codec. The default if this flag is not specified is
* implementation-specific. For example, the implementation of TurboJPEG for
* libjpeg[-turbo] 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.
*/
public static final int FLAG_ACCURATEDCT = 4096;
/**
* Immediately discontinue the current compression/decompression/transform
* operation if the underlying codec throws a warning (non-fatal error). The
* default behavior is to allow the operation to complete unless a fatal
* error is encountered.
* operation if a warning (non-fatal error) occurs. The default behavior is
* to allow the operation to complete unless a fatal error is encountered.
* <p>
* NOTE: due to the design of the TurboJPEG Java API, only certain methods
* (specifically, {@link TJDecompressor TJDecompressor.decompress*()} methods
* with a void return type) will complete and leave the output image in a
* fully recoverable state after a non-fatal error occurs.
* with a void return type) will complete and leave the destination image in
* a fully recoverable state after a non-fatal error occurs.
*/
public static final int FLAG_STOPONWARNING = 8192;
/**
@@ -455,13 +456,13 @@ public final class TJ {
*/
public static final int NUMERR = 2;
/**
* The error was non-fatal and recoverable, but the image may still be
* corrupt.
* The error was non-fatal and recoverable, but the destination image may
* still be corrupt.
* <p>
* NOTE: due to the design of the TurboJPEG Java API, only certain methods
* (specifically, {@link TJDecompressor TJDecompressor.decompress*()} methods
* with a void return type) will complete and leave the output image in a
* fully recoverable state after a non-fatal error occurs.
* with a void return type) will complete and leave the destination image in
* a fully recoverable state after a non-fatal error occurs.
*/
public static final int ERR_WARNING = 0;
/**
@@ -479,7 +480,7 @@ public final class TJ {
* @param height the height (in pixels) of the JPEG image
*
* @param jpegSubsamp the level of chrominance subsampling to be used when
* generating the JPEG image (one of {@link TJ TJ.SAMP_*})
* generating the JPEG image (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the maximum size of the buffer (in bytes) required to hold a JPEG
* image with the given width, height, and level of chrominance subsampling.
@@ -487,23 +488,27 @@ public final class TJ {
public static native int bufSize(int width, int height, int jpegSubsamp);
/**
* Returns the size of the buffer (in bytes) required to hold a YUV planar
* image with the given width, height, and level of chrominance subsampling.
* Returns the size of the buffer (in bytes) required to hold a unified
* planar YUV image with the given width, height, and level of chrominance
* subsampling.
*
* @param width the width (in pixels) of the YUV image
*
* @param pad the width of each line in each plane of the image is padded to
* the nearest multiple of this number of bytes (must be a power of 2.)
* @param align row alignment (in bytes) of the YUV image (must be a power of
* 2.) Setting this parameter to n specifies that each row in each plane of
* the YUV image will be padded to the nearest multiple of n bytes
* (1 = unpadded.)
*
* @param height the height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV
* image (one of {@link TJ TJ.SAMP_*})
* image (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the size of the buffer (in bytes) required to hold a YUV planar
* image with the given width, height, and level of chrominance subsampling.
* @return the size of the buffer (in bytes) required to hold a unified
* planar YUV image with the given width, height, and level of chrominance
* subsampling.
*/
public static native int bufSizeYUV(int width, int pad, int height,
public static native int bufSizeYUV(int width, int align, int height,
int subsamp);
/**
@@ -523,16 +528,16 @@ public final class TJ {
* @param width width (in pixels) of the YUV image. NOTE: this is the width
* of the whole image, not the plane width.
*
* @param stride bytes per line in the image plane.
* @param stride bytes per row in the image plane.
*
* @param height height (in pixels) of the YUV image. NOTE: this is the
* height of the whole image, not the plane height.
*
* @param subsamp the level of chrominance subsampling used in the YUV
* image (one of {@link TJ TJ.SAMP_*})
* image (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the size of the buffer (in bytes) required to hold a YUV planar
* image with the given parameters.
* @return the size of the buffer (in bytes) required to hold a YUV image
* plane with the given parameters.
*/
public static native int planeSizeYUV(int componentID, int width, int stride,
int height, int subsamp);
@@ -547,7 +552,7 @@ public final class TJ {
* @param width width (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV image
* (one of {@link TJ TJ.SAMP_*})
* (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the plane width of a YUV image plane with the given parameters.
*/
@@ -563,7 +568,7 @@ public final class TJ {
* @param height height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV image
* (one of {@link TJ TJ.SAMP_*})
* (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the plane height of a YUV image plane with the given parameters.
*/
@@ -571,11 +576,11 @@ public final class TJ {
int subsamp);
/**
* Returns a list of fractional scaling factors that the JPEG decompressor in
* this implementation of TurboJPEG supports.
* Returns a list of fractional scaling factors that the JPEG decompressor
* supports.
*
* @return a list of fractional scaling factors that the JPEG decompressor in
* this implementation of TurboJPEG supports.
* @return a list of fractional scaling factors that the JPEG decompressor
* supports.
*/
public static native TJScalingFactor[] getScalingFactors();