#include <dvmjpeg.h>
The struct JpegHdr corresponds to the JPEG frame header.
typedef struct JpegHdr {
short width;
short height;
short restartInterval;
short numOfQts;
char precision;
unsigned char numComps;
char blockWidth[3];
char blockHeight[3];
char qtId[3];
char compId[3];
char maxBlockWidth;
char maxBlockHeight;
JpegQt qt[4];
JpegHt ht[4];
} JpegHdr;
- width
- Width of the image in pixels
- height
- Height of the image in pixels
- restartInterval
- The restart interval for MCUs. An MCU (Minimum Coding Unit) is the smallest collection of blocks that correspond to an area in the decoded image. For instance, if the image is interleaved (meaning more than one component is encoded in a scan) and encoded using 4:2:2 subsampling, then for every block in the U and V planes, there are 2 blocks from the Y plane. These four blocks (one from the U plane, one from the V plane, and two from the Y plane) are called an MCU, and correspond to a 16x8 pixel region of the image.
In non-interleaved images (every color plane is stored in a seperate scan), an MCU corresponds to one block.
After every restartInterval MCUs, the predictor value for the DC components is reset to 0 (i.e the DC is not predicted from the previous DC). If restartInverval is 0, then all DC values in the image are predicted. If restartInterval is 1, then all DC values are non-predicted.
- numOfQts
- Number of quantization tables in this header.
- precision
- The sample precision - 8 or 12
- numComps
- The number of components (color planes) in the image. This is typically 1 for gray scale images, or 3 for color images.
- blockWidth[i]
- Horizontal blocks per MCU of component i
- blockHeight[i]
- Vertical blocks per MCU of component i
- qtid[i]
- ID of the quantization table to use for component i
- compId[i]
- Unique id assigned to component i in the bistream. compId[i] is often equal to i.
- maxBlockWidth
- The maximum of the blockWidth[] values.
- maxBlockHeight
- The maximum of the blockHeight[] values.
- qt[i]
- The ith quantization table in the bitstream (see the JpegQt type below). The total number of quantization table used is given by numOfQts.
- ht[i]
- The ith Huffman table in the bitstream. (see the JpegHt type below).
JpegQt holds the information about the quantization table of a JPEG image.
typedef struct JpegQt {
char precision;
short v[64];
} JpegQt;
- precision
- The precision of the quantization factors - either 8 or 16.
- v[]
- Array of quantization factors in row major order.
A JpegHt holds the information about the Huffman table of a JPEG image. The information is this representation is packed in the same way as in JPEG bitstreams.
typedef struct JpegHt {
int valid;
unsigned char dcBits[16];
unsigned char *dcVals;
unsigned char acBits[16];
unsigned char *acVals;
} JpegHt;
- valid
- This slot indicates if this huffman table is used or not. The last bit is set if the DC table is valid; the second last bit is set if the AC table is valid. In other words, valid == 3 if both DC and AC table are valid, valid == 2 if only AC table is used, valid == 1 if only DC table is used, and valid == 0 if both table are invalid.
- dcBits,dcVals
- The DC table as seen in the bitstream.
- acBits,acVals
- The AC table as seen in the bitstream.
JpegScanHdr maintains data from a JPEG scan header. Each scan encodes one or more component (color plane).
typedef struct JpegScanHdr {
int numComps;
char scanid[3];
char dcid[3];
char acid[3];
} JpegScanHdr;
- numComps
- number of components present in this scan
- scanid[i]
- the component number of the ith scan component (in order of appearance). Note that scanid[i] is the index used to look up all the component information in the JpegHdr
- dcid[i]
- the id of the dc huffman table to use to decode the ith scan component
- acid[i]
- the id of the ac huffman table to use to decode the ith scan component
This structure maintains "unpacked" Huffman tables for all components. It is primarily used in encoding. It contains, for each component, 4096 pairs of (code, symbol) for DC coefficients, and 256 pairs (code, symbol) for AC coefficients. There is also a table of 1024 entries specifying the number of bits in the huffman code for AC coefficients.
typedef struct JpegHuffTable {
int numOfComponents;
unsigned short *dcCode;
unsigned short *dcSymbol;
unsigned short *acCode;
unsigned short *acSymbol;
unsigned char *acNumOfBits;
} JpegHuffTable;
- numOfComponents
- Number of components in this JPEG file. This is usually 3 (for Y, U, V) although other values are possible.
- dcCode
- An array of numOfComponents*4096 elements, containing the codes for dc coefficients. The codes for components i (0,1,2,..) starts at position i*4096.
- dcSymbol
- An array of numOfComponents*4096 elements, containing the symbols for dc coefficients. The symbols for components i (0,1,2,..) starts at position i*4096.
- acCode
- An array of numOfComponents*256 elements, containing the codes for ac coefficients. The codes for component i (0,1,2,..) starts at position i*256.
- acSymbol
- An array of numOfComponents*256 elements, containing the symbols for ac coefficients. The symbols for component i (0,1,2,..) starts at position i*256.
- acNumOfBits
- An array of numOfComponents*1024 elements, containing the table for the number of bits of huffman code. The elements for component i (0,1,2,..) start at position i*1024.
These are the returned codes from various JPEG operations.
#define DVM_JPEG_OK 0
#define DVM_JPEG_INVALID_ID -1
#define DVM_JPEG_INVALID_PRECISION -2
#define DVM_JPEG_WRONG_COMPONENTS -3
#define DVM_JPEG_INVALID_WIDTH -4
#define DVM_JPEG_INVALID_HEIGHT -5
#define DVM_JPEG_INVALID_MARKER -6
#define DVM_JPEG_AC_UNSUPPORTED -7
JpegHdr *JpegHdrNew()
This function allocates a new JpegHdr and returns a handle to it. Returns NULL if allocation failed.
void JpegHdrFree (JpegHdr *hdr)
Deallocates the JpegHdr pointed to by hdr.
JpegScanHdr *JpegScanHdrNew ( )
Allocates a new JpegScanHdr, and return a pointer to it. Returns NULL if allocation failed.
void JpegScanHdrFree (JpegScanHdr *scanHdr)
Deallocates the JpegScanHdr pointed to by scanHdr.
int JpegHdrParse (BitParser *bp, JpegHdr *hdr)
Parses off a JPEG header and fills hdr from where BitParser bp is pointing. Return the number of bytes parsed from the bitstream. Returns DVM_JPEG_INVALID_MARKER if an invalid marker is encountered. DVM_JPEG_AC_UNSUPPORTED is returned if a DAC marker is encountered.
int JpegScanHdrParse (BitParser *bp, JpegHdr *hdr, JpegScanHdr *scanHdr)
Parses off a JPEG scan header from where the BitParser bp is pointing to, and initialize the scan header. Return the number of bytes parsed from the bitstream. an error is encoutered. Returns DVM_JPEG_INVALID_MARKER if an invalid marker is encountered. DVM_JPEG_AC_UNSUPPORTED is returned if a DAC marker is encountered.
int JpegScanParse (BitParser *bp, JpegHdr *hdr, JpegScanHdr *scanHdr, ScImage *scans[], int num)
Parse a scan from the bitstream the bitparser is pointing to. The array of ScImage scans is initialized. num indicates the number of scans in the array scans. Each ScImage will contain unscaled coefficients, so the function ScIToByte can be called directly on these ScImages.
If the number of components does not match the one specified in the header, DVM_JPEG_WRONG_COMPONENTS is returned. If the width and height does not match the one specified in the header, DVM_JPEG_INVALID_WIDTH and DVM_JPEG_INVALID_HEIGHT will be returned respectively.
int JpegScanSelectiveParse (BitParser *bp, JpegHdr *hdr, JpegScanHdr *scanHdr, ScImage *scans[], int num)
Parse selective planes from the BitStream the BitParser is pointing to. Some ScImages can be NULL, which instructs the routine not to decode that plane.
If the number of components does not match the one specified in the header, DVM_JPEG_WRONG_COMPONENTS is returned. If the width and height does not match the one specified in the header, DVM_JPEG_INVALID_WIDTH and DVM_JPEG_INVALID_HEIGHT will be returned respectively.
int JpegScanIncParseStart (BitParser *bp, JpegHdr *hdr, JpegScanHdr *scanHdr, ScImage *scans[], int num)
Begins an incremental scan parse. This routine does not actually read anything off the bitstream, but sets up some state variables. It returns the total number of MCUs in the scan. If the number of components does not match the one specified in the header, DVM_JPEG_WRONG_COMPONENTS is returned. If the width and height does not match the one specified in the header, DVM_JPEG_INVALID_WIDTH and DVM_JPEG_INVALID_HEIGHT will be returned respectively.
int JpegScanIncParse (BitParser *bp, JpegHdr *hdr, JpegScanHdr *scanHdr, int howMany, ScImage *scans[], int num)
Continues incremental scan parse. howmany is the number of MCUs we want to parse. It returns the total number of MCUs parsed off since the incremental parse began.
int JpegScanIncParseEnd (BitParser *bp, JpegHdr *hdr, JpegScanHdr *scanHdr, ScImage *scans[], int num)
Ends an incremental scan parse.
int JpegHdrHtEncode (JpegHdr *hdr, BitParser *bp)
Encodes the huffman table embedded in the JPEG header structure hdr into BitStream using BitParser bp. This should be done before the JPEG header or scan header is encoded. Returns the number of bytes encoded.
int JpegHdrQtEncode (JpegHdr *hdr, BitParser *bp)
Encodes the quantization table embedded in the JPEG header hdr into BitStream using BitParser bp. This should be done before the JPEG header or scan header is encoded. Returns the number of bytes encoded.
int JpegHdrEncode (JpegHdr *hdr, int baseline, BitParser *bp)
Encodes the JPEG header hdr into BitStream using BitParser bp. baseline specifies if the parameters conform to the baseline JPEG specification or not. Returns the number of bytes encoded.
int JpegScanHdrEncode (JpegHdr *hdr, JpegScanHdr *scanHdr, BitParser *bp)
Encodes the JPEG scan header scanHdr into the BitStreams attached to the BitParser bp. Returns the number of bytes encoded into the bitstream.
int JpegScanEncode (JpegHdr *hdr, JpegScanHdr *scanHdr, JpegHuffTable *huffTable, ScImage *scans[], int num, BitParser *bp)
Encodes a complete scan into the bitstream. This routine does not put a marker to end the image, so multiple calls to this routine are possible. Returns the number of bytes encoded into the bitstream. If the number of components does not match the one specified in the header, DVM_JPEG_WRONG_COMPONENTS is returned. If the width and height do not match those specified in the header, DVM_JPEG_INVALID_WIDTH and/or DVM_JPEG_INVALID_HEIGHT will be returned respectively.
int JpegScanEncode420 (JpegHdr *hdr, JpegScanHdr *scanHdr, JpegHuffTable *huffTable, ScImage *scY, ScImage *scU, ScImage *scV, BitParser *bp)
Encodes a complete scan into the bitstream. This scan consists of three components, each corresponding to a plane in YUV color space based on 4:2:0 subsampling. Does not put a marker to end the image, so multiple calls to this routine are possible.
int JpegScanEncode422 (JpegHdr *hdr, JpegScanHdr *scanHdr, JpegHuffTable *huffTable, ScImage *scY, ScImage *scU, ScImage *scV, BitParser *bp)
Encodes a complete scan into the bitstream. This scan consists of three components, each corresponding to a plane in YUV color space based on 4:2:2 subsampling. Does not put a marker to end the image, so multiple calls to this routine are possible.
int JpegScanIncEncode420 (JpegHdr *hdr, JpegScanHdr *scanHdr, JpegHuffTable *huffTable, ScImage *scY, ScImage *scU, ScImage *scV, BitParser *bp)
Incremental version of scan encoding. The first call and last call to this primitives should pass NULL as an argument for scY. First call this function with NULL as scY to initilize the encoding. The last call will clean up the BitParser. For all calls in between, this function will encode the ScImages passed in.
int JpegScanIncEncode422 (JpegHdr *hdr, JpegScanHdr *scanHdr, JpegHuffTable *huffTable, ScImage *scY, ScImage *scU, ScImage *scV, BitParser *bp)
Incremental version of scan encoding. The first call and last call to this primitives should pass NULL as an argument for scY. First call this function with NULL as scY to initilize the encoding. The last call will clean up the BitParser. For all calls in between, this function will encode the ScImages passed in.
int JpegStartCodeEncode (BitParser *bp)
Outputs the SOI (start of image) marker into the bitstream, to signify the beginning of an image. This should be called before the encoding all headers and scans. Returns the number of bytes encoded, which should always be 2.
int JpegEndCodeEncode (BitParser *bp)
Outputs the EOI (end of image) marker onto the bitstream, to signify the image end. This should be called after all headers and scanned are encoded. Returns the number of bytes encoded (which should always be 2)
JpegHuffTable *JpegHuffTableNew (int numOfComponents)
Creates a new Huffman table of numOfComponents components. A handle to an empty Huffman table is returned. JpegHuffTableInit should be called to initialize the huffman table.
void JpegHuffTableInit (JpegHdr *jpegHdr, JpegScanHdr *scanHdr, JpegHuffTable *huffTable)
Initialize the Huffman table huffTable based on specification in the headers jpegHdr and scanHdr.
void JpegHdrHuffTableFree huffTable
Deallocates the memory allocated for the Huffman table huffTable.
short JpegHdrGetWidth (JpegHdr *hdr)
short JpegHdrGetHeight (JpegHdr *hdr)
short JpegHdrGetRestartInterval (JpegHdr *hdr)
unsigned char JpegHdrGetNumOfComponents (JpegHdr *hdr)
unsigned char JpegHdrGetPrecision (JpegHdr *hdr)
unsigned char JpegHdrGetMaxBlockHeight (JpegHdr *hdr)
unsigned char JpegHdrGetMaxBlockWidth (JpegHdr *hdr)
These functions retrieve the following information about the JpegHdr hdr :
- width of the image in pixels
- height of the image in pixels
- number of MCU is restart interval
- number of components in the image
- number of bits in each samples
- maximum block height among the components
- maximum block width among the components
char JpegHdrGetComponentId (JpegHdr *hdr, int i)
char JpegHdrGetQtId (JpegHdr *hdr, int i)
char JpegHdrGetBlockWidth (JpegHdr *hdr, int i)
char JpegHdrGetBlockHeight (JpegHdr *hdr, int i)
Returns the following information about the i-th components :
- the ID of this component
- the quantization table ID of this component
- block width of this component
- block height of this component
short *JpegHdrGetQt(JpegHdr *hdr)
Returns the quantization table of the JPEG hdr as an array of 64 elements. This array should not be freed.
char JpegScanHdrGetNumOfComponents (JpegScanHdr *hdr)
char JpegScanHdrGetScanId (JpegScanHdr *hdr, int i)
char JpegScanHdrGetDcId (JpegScanHdr *hdr, int i)
char JpegScanHdrGetAcId (JpegScanHdr *hdr, int i)
Returns the following information contained in the scan header hdr :
- the number of components in this scan
- the scan id for component i
- ID for DC huffman table for component i
- ID for AC huffman table for component i
void JpegHdrSetWidth (JpegHdr *hdr)
void JpegHdrSetHeight (JpegHdr *hdr)
void JpegHdrSetNumOfComponents (JpegHdr *hdr)
void JpegHdrSetPrecision (JpegHdr *hdr)
void JpegHdrSetRestartInterval (JpegHdr *hdr)
These functions set the following information about the JpegHdr hdr :
- width of the image in pixels
- height of the image in pixels
- number of components in the image
- number of bits in each samples
- number of MCU is restart interval
void JpegHdrStdQtInit (JpegHdr *hdr)
Initialized the quantization table in the header to the standard quantization table.
void JpegHdrStdHtInit (JpegHdr *hdr)
Initialized the huffman table in the header to the standard huffman table.
void JpegHdrSetQt (JpegHdr *hdr, int id, int precision, short qList[])
Set the values and precision in the quantization table id of header hdr. id have to be either 0, 1, 2, or 3. precision specifies the number of bits in each quantization value and must be either 8 or 16. The values of the quantization table is given in the array qList[] of 64 elements. Returns DVM_JPEG_INVALID_ID if id is invalid. Returns DVM_JPEG_INVALID_PRECISION if precision is invalid. Otherwise returns DVM_JPEG_OK.
void JpegHdrSetQtIds (JpegHdr *hdr, char qtIdList[], int n);
Initialize each component's quantization table ids in header hdr. The ids are specified by an array of n elements qtIdList. n should be the same as the number of components in the image.
char JpegHdrSetComponentId(JpegHdr *hdr, int i, int id)
char JpegHdrSetQtId(JpegHdr *hdr, int i, int id)
Sets the following information about the i-th components :
- the ID of this component
- the quantization table ID of this component
char JpegHdrSetBlockWidth(JpegHdr *hdr, int i, int width)
char JpegHdrSetBlockHeight(JpegHdr *hdr, int i, int height)
Sets the block width and block height of the i-th components in a JPEG header hdr.
void JpegHdrSetMaxBlockHeight (JpegHdr *hdr)
void JpegHdrSetMaxBlockWidth (JpegHdr *hdr)
Sets the maximum block width and maximum block height among the components in JPEG header hdr.
void JpegHdrSetBlockWidths(JpegHdr *hdr, char widths[], int n);
Set the block width for all components in JPEG header hdr. The maximum block width will be updated by this functions. The widths are specified by an array of n elements widths. n must be the same as the number of components in the image.
This is an alternative to calling JpegHdrSetBlockWidth and JpegHdrSetMaxBlockWidth.
void JpegHdrSetBlockHeights(JpegHdr *hdr, char heights[], int n);
Set the block height for all components in JPEG header hdr. The maximum block height will be updated by this functions. The heights are specified by an array of n elements heights. n must be the same as the number of components in the image.
char JpegScanHdrSetNumOfComponents(JpegScanHdr *hdr, int n)
char JpegScanHdrSetScanId(JpegScanHdr *hdr, int i, int id)
char JpegScanHdrSetDcId(JpegScanHdr *hdr, int i, int id)
char JpegScanHdrSetAcId(JpegScanHdr *hdr, int i, int id)
Set the following information contained in the scan header hdr :
- the number of components in this scan
- the scan id for component i
- ID for DC huffman table for component i
- ID for AC huffman table for component i
void JpegScanHdrSetScanIds(JpegScanHdr *scanHdr, char scanIds[], int n);
Set the scan ids for all component in this scan. The scan ids are specified by an array of n elements scanIds. n must be the same as the number of components in the scan.
void JpegScanHdrSetDcIds(JpegScanHdr *scanHdr, char dcIds[], int n);
Set the dc ids for all component in this scan. The dc ids are specified by an array of n elements dcIds. n must be the same as the number of components in the scan.
void JpegScanHdrSetAcIds(JpegScanHdr *scanHdr, char acIds[], int n);
Set the ac ids for all component in this scan. The ac ids are specified by an array of n elements acIds. n must be the same as the number of components in the scan.
Last updated : Saturday, November 14, 1998, 07:50 PM