YUV Image Format Notes

Technically, the JPEG format uses the YCbCr colorspace (which is technically not a colorspace but a color transform), but per the convention of the digital video community, the TurboJPEG API uses "YUV" to refer to an image format consisting of Y, Cb, and Cr image planes.

Each plane is simply a 2D array of bytes, each byte representing the value of one of the components (Y, Cb, or Cr) at a particular location in the image. The "component width" and "component height" of each plane are determined by the image width, height, and level of chrominance subsampling. For the luminance plane, the component width is the image width padded to the nearest multiple of the horizontal subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the component height of the luminance plane is the image height padded to the nearest multiple of the vertical subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4 or grayscale.) This is irrespective of any additional padding that may be specified as an argument to the various YUV functions. The component width of the chrominance planes is equal to the component width of the luminance plane divided by the horizontal subsampling factor, and the component height of the chrominance planes is equal to the component height of the luminance plane divided by the vertical subsampling factor.

Each plane is simply a 2D array of bytes, each byte representing the value of one of the components (Y, Cb, or Cr) at a particular location in the image. The width and height of each plane are determined by the image width, height, and level of chrominance subsampling. The luminance plane width is the image width padded to the nearest multiple of the horizontal subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the luminance plane height is the image height padded to the nearest multiple of the vertical subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4 or grayscale.) This is irrespective of any additional padding that may be specified as an argument to the various YUV functions. The chrominance plane width is equal to the luminance plane width divided by the horizontal subsampling factor, and the chrominance plane height is equal to the luminance plane height divided by the vertical subsampling factor.

For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is used, then the luminance plane would be 36 x 35 bytes, and each of the chrominance planes would be 18 x 35 bytes. If you specify a line padding of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and each of the chrominance planes would be 20 x 35 bytes.

Macro Definition Documentation

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.

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.

Lossless transforms work by moving the raw DCT 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.

Parameters

- - + + - +

handle	a handle to a TurboJPEG transformer instance
jpegBuf	pointer to a buffer containing the JPEG image to transform
jpegSize	size of the JPEG image (in bytes)
jpegBuf	pointer to a buffer containing the JPEG source image to transform
jpegSize	size of the JPEG source image (in bytes)
n	the number of transformed JPEG images to generate
dstBufs	pointer to an array of n image buffers. `dstBufs[i]` will receive a JPEG image that has been transformed using the parameters in `transforms[i]`. 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, @@ -2121,7 +2275,7 @@ If you choose option 1, `*jpegSize` should be set to the size of your If you choose option 1, `dstSizes[i]` should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check `dstBufs[i]` upon return from this function, as it may have changed.
dstSizes	pointer to an array of n unsigned long variables that will receive the actual sizes (in bytes) of each transformed JPEG image. If `dstBufs[i]` points to a pre-allocated buffer, then `dstSizes[i]` should be set to the size of the buffer. Upon return, `dstSizes[i]` will contain the size of the JPEG image (in bytes.)
transforms	pointer to an array of n tjtransform structures, each of which specifies the transform parameters and/or cropping region for the corresponding transformed output image.
flags	the bitwise OR of one or more of the flags.
flags	the bitwise OR of one or more of the flags

diff --git a/doc/html/search/all_74.js b/doc/html/search/all_74.js index 7b50830..5b46106 100644 --- a/doc/html/search/all_74.js +++ b/doc/html/search/all_74.js @@ -56,6 +56,9 @@ var searchData= ['tjpf_5fxbgr',['TJPF_XBGR',['../group___turbo_j_p_e_g.html#ggac916144e26c3817ac514e64ae5d12e2aaf6603b27147de47e212e75dac027b2af',1,'turbojpeg.h']]], ['tjpf_5fxrgb',['TJPF_XRGB',['../group___turbo_j_p_e_g.html#ggac916144e26c3817ac514e64ae5d12e2aadae996905efcfa3b42a0bb3bea7f9d84',1,'turbojpeg.h']]], ['tjpixelsize',['tjPixelSize',['../group___turbo_j_p_e_g.html#gad77cf8fe5b2bfd3cb3f53098146abb4c',1,'turbojpeg.h']]], + ['tjplaneheight',['tjPlaneHeight',['../group___turbo_j_p_e_g.html#ga1a209696c6a80748f20e134b3c64789f',1,'turbojpeg.h']]], + ['tjplanesizeyuv',['tjPlaneSizeYUV',['../group___turbo_j_p_e_g.html#ga6f98d977bfa9d167c97172e876ba61e2',1,'turbojpeg.h']]], + ['tjplanewidth',['tjPlaneWidth',['../group___turbo_j_p_e_g.html#ga63fb66bb1e36c74008c4634360becbb1',1,'turbojpeg.h']]], ['tjredoffset',['tjRedOffset',['../group___turbo_j_p_e_g.html#gadd9b446742ac8a3923f7992c7988fea8',1,'turbojpeg.h']]], ['tjregion',['tjregion',['../structtjregion.html',1,'']]], ['tjsamp',['TJSAMP',['../group___turbo_j_p_e_g.html#ga1d047060ea80bb9820d540bb928e9074',1,'turbojpeg.h']]], @@ -67,7 +70,7 @@ var searchData= ['tjsamp_5fgray',['TJSAMP_GRAY',['../group___turbo_j_p_e_g.html#gga1d047060ea80bb9820d540bb928e9074a3f1c9504842ddc7a48d0f690754b6248',1,'turbojpeg.h']]], ['tjscaled',['TJSCALED',['../group___turbo_j_p_e_g.html#ga84878bb65404204743aa18cac02781df',1,'turbojpeg.h']]], ['tjscalingfactor',['tjscalingfactor',['../structtjscalingfactor.html',1,'']]], - ['tjtransform',['tjtransform',['../structtjtransform.html',1,'tjtransform'],['../group___turbo_j_p_e_g.html#gaa29f3189c41be12ec5dee7caec318a31',1,'tjtransform(): turbojpeg.h'],['../group___turbo_j_p_e_g.html#gae403193ceb4aafb7e0f56ab587b48616',1,'tjTransform(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int n, unsigned char **dstBufs, unsigned long *dstSizes, tjtransform *transforms, int flags): turbojpeg.h']]], + ['tjtransform',['tjtransform',['../structtjtransform.html',1,'tjtransform'],['../group___turbo_j_p_e_g.html#gae403193ceb4aafb7e0f56ab587b48616',1,'tjTransform(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int n, unsigned char **dstBufs, unsigned long *dstSizes, tjtransform *transforms, int flags): turbojpeg.h'],['../group___turbo_j_p_e_g.html#gaa29f3189c41be12ec5dee7caec318a31',1,'tjtransform(): turbojpeg.h']]], ['tjxop',['TJXOP',['../group___turbo_j_p_e_g.html#ga2de531af4e7e6c4f124908376b354866',1,'turbojpeg.h']]], ['tjxop_5fhflip',['TJXOP_HFLIP',['../group___turbo_j_p_e_g.html#gga2de531af4e7e6c4f124908376b354866aa0df69776caa30f0fa28e26332d311ce',1,'turbojpeg.h']]], ['tjxop_5fnone',['TJXOP_NONE',['../group___turbo_j_p_e_g.html#gga2de531af4e7e6c4f124908376b354866aad88c0366cd3f7d0eac9d7a3fa1c2c27',1,'turbojpeg.h']]], diff --git a/doc/html/search/functions_74.js b/doc/html/search/functions_74.js index 35a3f8e..73b7ee9 100644 --- a/doc/html/search/functions_74.js +++ b/doc/html/search/functions_74.js @@ -21,5 +21,8 @@ var searchData= ['tjinitcompress',['tjInitCompress',['../group___turbo_j_p_e_g.html#ga3d10c47fbe4a2489a2b30c931551d01a',1,'turbojpeg.h']]], ['tjinitdecompress',['tjInitDecompress',['../group___turbo_j_p_e_g.html#gae5408179d041e2a2f7199c8283cf649e',1,'turbojpeg.h']]], ['tjinittransform',['tjInitTransform',['../group___turbo_j_p_e_g.html#ga3155b775bfbac9dbba869b95a0367902',1,'turbojpeg.h']]], + ['tjplaneheight',['tjPlaneHeight',['../group___turbo_j_p_e_g.html#ga1a209696c6a80748f20e134b3c64789f',1,'turbojpeg.h']]], + ['tjplanesizeyuv',['tjPlaneSizeYUV',['../group___turbo_j_p_e_g.html#ga6f98d977bfa9d167c97172e876ba61e2',1,'turbojpeg.h']]], + ['tjplanewidth',['tjPlaneWidth',['../group___turbo_j_p_e_g.html#ga63fb66bb1e36c74008c4634360becbb1',1,'turbojpeg.h']]], ['tjtransform',['tjTransform',['../group___turbo_j_p_e_g.html#gae403193ceb4aafb7e0f56ab587b48616',1,'turbojpeg.h']]] ]; -- cgit v1.2.3

width	width of the image (in pixels)
height	height of the image (in pixels)
width	width (in pixels) of the image
height	height (in pixels) of the image
jpegSubsamp	the level of chrominance subsampling to be used when generating the JPEG image (see Chrominance subsampling options.)

handle	a handle to a TurboJPEG compressor or transformer instance
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 image to be compressed. These planes can be contiguous or non-contiguous in memory. Each plane should be at least **{component stride} {component height}*** bytes in size. (See below for a description of stride, and refer to YUV Image Format Notes for a description of component height.)
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 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 tjPlaneSizeYUV() for the given image width, height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details.
width	width (in pixels) of the source image. If the width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed within TurboJPEG.
strides	an array of integers, each specifying the number of bytes per line 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 component width for the plane. If `strides` is NULL, then the strides for all planes will be set to their respective component widths. You can adjust the strides in order to specify an arbitrary amount of line padding in each plane or to create a JPEG image from a subregion of a larger YUV planar image.
strides	an array of integers, each specifying the number of bytes per line 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 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 line padding in each plane or to create a JPEG image from a subregion of a larger YUV planar image.
height	height (in pixels) of the source image. If the height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed within TurboJPEG.
subsamp	the level of chrominance subsampling used in the source image (see Chrominance subsampling options.)
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: @@ -1199,7 +1208,7 @@ If you choose option 1, `jpegSize` should be set to the size of your If you choose option 1, `jpegSize` should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check `*jpegBuf` upon return from this function, as it may have changed.
jpegSize	pointer to an unsigned long variable that holds the size of the JPEG image 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.)
jpegQual	the image quality of the generated JPEG image (1 = worst, 100 = best)
flags	the bitwise OR of one or more of the flags.
flags	the bitwise OR of one or more of the flags

handle	a handle to a TurboJPEG decompressor or transformer instance
srcPlanes	an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if decoding a grayscale image) that contain a YUV image to be decoded. These planes can be contiguous or non-contiguous in memory. Each plane should be at least **{component stride} {component height}*** bytes in size. (See below for a description of stride, and refer to YUV Image Format Notes for a description of component height.)
strides	an array of integers, each specifying the number of bytes per line 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 component width for the plane. If `strides` is NULL, then the strides for all planes will be set to their respective component widths. You can adjust the strides in order to specify an arbitrary amount of line padding in each plane or to decode a subregion of a larger YUV planar image.
srcPlanes	an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if decoding a grayscale image) that contain a YUV image to be decoded. These planes can be contiguous or non-contiguous in memory. The size of each plane should match the value returned by tjPlaneSizeYUV() for the given image width, height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details.
strides	an array of integers, each specifying the number of bytes per line 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 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 line padding in each plane or to decode a subregion of a larger YUV planar image.
subsamp	the level of chrominance subsampling used in the YUV source image (see Chrominance subsampling options.)
dstBuf	pointer to an image buffer that will receive the decoded image. This buffer should normally be `pitch * height` bytes in size, but the `dstBuf` pointer can also be used to decode into a specific region of a larger buffer.
width	width (in pixels) of the source and destination images
pitch	bytes per line of the destination image. Normally, this should be `width * tjPixelSize[pixelFormat]` if the destination image is unpadded, or `TJPAD(width * tjPixelSize[pixelFormat])` if each line of the destination image should be padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use the pitch parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to `width * tjPixelSize[pixelFormat]`.
pitch	bytes per line in the destination image. Normally, this should be `width * tjPixelSize[pixelFormat]` if the destination image is unpadded, or `TJPAD(width * tjPixelSize[pixelFormat])` if each line of the destination image should be padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use the pitch parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to `width * tjPixelSize[pixelFormat]`.
height	height (in pixels) of the source and destination images
pixelFormat	pixel format of the destination image (see Pixel formats.)
flags	the bitwise OR of one or more of the flags.
flags	the bitwise OR of one or more of the flags

DLLEXPORT int tjPlaneHeight	(	int	componentID,
		int	height,
		int	subsamp
	)

componentID	ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr)
height	height (in pixels) of the YUV image
subsamp	level of chrominance subsampling in the image (see Chrominance subsampling options.)

DLLEXPORT unsigned long DLLCALL tjPlaneSizeYUV	(	int	componentID,
		int	width,
		int	stride,
		int	height,
		int	subsamp
	)

DLLEXPORT int tjPlaneWidth	(	int	componentID,
		int	width,
		int	subsamp
	)