jpegparser

jpegparser — Convenience library for JPEG bitstream parsing.

Synopsis

#include <gst/codecparsers/gstjpegparser.h>

#define             GST_JPEG_MAX_FRAME_COMPONENTS
#define             GST_JPEG_MAX_SCAN_COMPONENTS
#define             GST_JPEG_MAX_QUANT_ELEMENTS
#define             GST_JPEG_MARKER_SOF_MIN
#define             GST_JPEG_MARKER_SOF_MAX
#define             GST_JPEG_MARKER_APP_MIN
#define             GST_JPEG_MARKER_APP_MAX
#define             GST_JPEG_MARKER_RST_MIN
#define             GST_JPEG_MARKER_RST_MAX
enum                GstJpegEntropyCodingMode;
enum                GstJpegProfile;
struct              GstJpegSegment;
gboolean            gst_jpeg_parse                      (GstJpegSegment *seg,
                                                         const guint8 *data,
                                                         gsize size,
                                                         guint offset);
struct              GstJpegFrameHdr;
struct              GstJpegFrameComponent;
gboolean            gst_jpeg_segment_parse_frame_header (const GstJpegSegment *segment,
                                                         GstJpegFrameHdr *frame_hdr);
struct              GstJpegScanHdr;
struct              GstJpegScanComponent;
gboolean            gst_jpeg_segment_parse_scan_header  (const GstJpegSegment *segment,
                                                         GstJpegScanHdr *scan_hdr);
struct              GstJpegHuffmanTables;
struct              GstJpegHuffmanTable;
gboolean            gst_jpeg_segment_parse_huffman_table
                                                        (const GstJpegSegment *segment,
                                                         GstJpegHuffmanTables *huff_tables);
struct              GstJpegQuantTable;
gboolean            gst_jpeg_segment_parse_quantization_table
                                                        (const GstJpegSegment *segment,
                                                         GstJpegQuantTables *quant_tables);
gboolean            gst_jpeg_segment_parse_restart_interval
                                                        (const GstJpegSegment *segment,
                                                         guint *interval);
void                gst_jpeg_get_default_quantization_tables
                                                        (GstJpegQuantTables *quant_tables);
void                gst_jpeg_get_default_huffman_tables (GstJpegHuffmanTables *huff_tables);

Description

Provides useful functions for parsing JPEG images

Details

GST_JPEG_MAX_FRAME_COMPONENTS

#define GST_JPEG_MAX_FRAME_COMPONENTS   256

Maximum number of image components in a frame (Nf).

Since 1.6


GST_JPEG_MAX_SCAN_COMPONENTS

#define GST_JPEG_MAX_SCAN_COMPONENTS    4

Maximum number of image components in a scan (Ns).

Since 1.6


GST_JPEG_MAX_QUANT_ELEMENTS

#define GST_JPEG_MAX_QUANT_ELEMENTS     64

Number of elements in the quantization table.

Since 1.6


GST_JPEG_MARKER_SOF_MIN

#define GST_JPEG_MARKER_SOF_MIN GST_JPEG_MARKER_SOF0

GST_JPEG_MARKER_SOF_MAX

#define GST_JPEG_MARKER_SOF_MAX GST_JPEG_MARKER_SOF15

GST_JPEG_MARKER_APP_MIN

#define GST_JPEG_MARKER_APP_MIN GST_JPEG_MARKER_APP0

GST_JPEG_MARKER_APP_MAX

#define GST_JPEG_MARKER_APP_MAX GST_JPEG_MARKER_APP15

GST_JPEG_MARKER_RST_MIN

#define GST_JPEG_MARKER_RST_MIN GST_JPEG_MARKER_RST0

GST_JPEG_MARKER_RST_MAX

#define GST_JPEG_MARKER_RST_MAX GST_JPEG_MARKER_RST7

enum GstJpegEntropyCodingMode

typedef enum {
  GST_JPEG_ENTROPY_CODING_HUFFMAN       = 0x00,
  GST_JPEG_ENTROPY_CODING_ARITHMETIC    = 0x08
} GstJpegEntropyCodingMode;

JPEG entropy coding mode.

GST_JPEG_ENTROPY_CODING_HUFFMAN

Huffman coding

GST_JPEG_ENTROPY_CODING_ARITHMETIC

arithmetic coding

Since 1.6


enum GstJpegProfile

typedef enum {
  GST_JPEG_PROFILE_BASELINE     = 0x00,
  GST_JPEG_PROFILE_EXTENDED     = 0x01,
  GST_JPEG_PROFILE_PROGRESSIVE  = 0x02,
  GST_JPEG_PROFILE_LOSSLESS     = 0x03,
} GstJpegProfile;

JPEG encoding processes.

GST_JPEG_PROFILE_BASELINE

Baseline DCT

GST_JPEG_PROFILE_EXTENDED

Extended sequential DCT

GST_JPEG_PROFILE_PROGRESSIVE

Progressive DCT

GST_JPEG_PROFILE_LOSSLESS

Lossless (sequential)

Since 1.6


struct GstJpegSegment

struct GstJpegSegment {
  GstJpegMarker marker;
  const guint8 *data;
  guint offset;
  gssize size;
};

A structure that contains the type of a segment, its offset and its size.

GstJpegMarker marker;

The type of the segment that starts at offset

const guint8 *data;

the data containing the jpeg segment starting at offset

guint offset;

The offset to the segment start in bytes. This is the exact start of the segment, no marker code included

gssize size;

The size of the segment in bytes, or -1 if the end was not found. It is the exact size of the segment, without the sync byte and marker code but including any length bytes.

Since 1.6


gst_jpeg_parse ()

gboolean            gst_jpeg_parse                      (GstJpegSegment *seg,
                                                         const guint8 *data,
                                                         gsize size,
                                                         guint offset);

Parses the JPEG bitstream contained in data, and returns the detected segment as a GstJpegSegment.

Note that a valid segment may be returned with a length that exceeds the available data. It is up to the caller to make sure there's enough data available when parsing the segment.

segment :

pointer to a GstJpegSegment structure to fill in. [out]

data :

The data to parse

size :

The size of data

offset :

The offset from which to start parsing

Returns :

TRUE if a packet start code was found.

Since 1.6


struct GstJpegFrameHdr

struct GstJpegFrameHdr {
  guint8 sample_precision;              /* 2 .. 16      */
  guint16 width;                        /* 1 .. 65535   */
  guint16 height;                       /* 0 .. 65535   */
  guint8 num_components;                /* 1 .. 255     */
  GstJpegFrameComponent components[GST_JPEG_MAX_FRAME_COMPONENTS];
};

Frame header.

guint8 sample_precision;

Sample precision (P)

guint16 width;

Number of samples per line (X)

guint16 height;

Number of lines (Y)

guint8 num_components;

Number of image components in frame (Nf)

GstJpegFrameComponent components[GST_JPEG_MAX_FRAME_COMPONENTS];

Image components

Since 1.6


struct GstJpegFrameComponent

struct GstJpegFrameComponent {
  guint8 identifier;                    /* 0 .. 255     */
  guint8 horizontal_factor;             /* 1 .. 4       */
  guint8 vertical_factor;               /* 1 .. 4       */
  guint8 quant_table_selector;          /* 0 .. 3       */
};

Component-specification parameters.

guint8 identifier;

Component identifier (Ci)

guint8 horizontal_factor;

Horizontal sampling factor (Hi)

guint8 vertical_factor;

Vertical sampling factor (Vi)

guint8 quant_table_selector;

Quantization table destination selector (Tqi)

Since 1.6


gst_jpeg_segment_parse_frame_header ()

gboolean            gst_jpeg_segment_parse_frame_header (const GstJpegSegment *segment,
                                                         GstJpegFrameHdr *frame_hdr);

Parses the frame_hdr JPEG frame header structure members from segment.

The caller must make sure there is enough data for the whole segment available.

segment :

the JPEG segment

frame_hdr :

The GstJpegFrameHdr structure to fill in. [out]

Returns :

TRUE if the frame header was correctly parsed.

Since 1.6


struct GstJpegScanHdr

struct GstJpegScanHdr {
  guint8 num_components;                /* 1 .. 4       */
  GstJpegScanComponent components[GST_JPEG_MAX_SCAN_COMPONENTS];
};

Scan header.

guint8 num_components;

Number of image components in scan (Ns)

GstJpegScanComponent components[GST_JPEG_MAX_SCAN_COMPONENTS];

Image components

Since 1.6


struct GstJpegScanComponent

struct GstJpegScanComponent {
    guint8 component_selector;          /* 0 .. 255     */
    guint8 dc_selector;                 /* 0 .. 3       */
    guint8 ac_selector;                 /* 0 .. 3       */
};

Component-specification parameters.

guint8 component_selector;

Scan component selector (Csj)

guint8 dc_selector;

DC entropy coding table destination selector (Tdj)

guint8 ac_selector;

AC entropy coding table destination selector (Taj)

Since 1.6


gst_jpeg_segment_parse_scan_header ()

gboolean            gst_jpeg_segment_parse_scan_header  (const GstJpegSegment *segment,
                                                         GstJpegScanHdr *scan_hdr);

Parses the scan_hdr JPEG scan header structure members from segment.

The caller must make sure there is enough data for the whole segment available.

segment :

the JPEG segment

scan_hdr :

The GstJpegScanHdr structure to fill in. [out]

Returns :

TRUE if the scan header was correctly parsed

Since 1.6


struct GstJpegHuffmanTables

struct GstJpegHuffmanTables {
  GstJpegHuffmanTable dc_tables[GST_JPEG_MAX_SCAN_COMPONENTS];
  GstJpegHuffmanTable ac_tables[GST_JPEG_MAX_SCAN_COMPONENTS];
};

Helper data structure that holds all AC/DC Huffman tables used to decode an image.

GstJpegHuffmanTable dc_tables[GST_JPEG_MAX_SCAN_COMPONENTS];

DC Huffman tables

GstJpegHuffmanTable ac_tables[GST_JPEG_MAX_SCAN_COMPONENTS];

AC Huffman tables

Since 1.6


struct GstJpegHuffmanTable

struct GstJpegHuffmanTable {
  guint8 huf_bits[16];
  guint8 huf_values[256];
  gboolean valid;
};

Huffman table.

guint8 huf_bits[16];

Number of Huffman codes of length i + 1 (Li)

guint8 huf_values[256];

gboolean valid;

If the Huffman table is valid, which means it has already been parsed

Since 1.6


gst_jpeg_segment_parse_huffman_table ()

gboolean            gst_jpeg_segment_parse_huffman_table
                                                        (const GstJpegSegment *segment,
                                                         GstJpegHuffmanTables *huff_tables);

Parses the JPEG Huffman table structure members from segment.

The caller must make sure there is enough data for the whole segment available.

Note: huf_tables represents the complete set of possible Huffman tables. However, the parser will only write to the Huffman table specified by the table destination identifier (Th). While doing so, the valid flag of the specified Huffman table will also be set to TRUE;

segment :

the JPEG segment

huff_tables :

The GstJpegHuffmanTables structure to fill in. [out]

Returns :

TRUE if the Huffman table was correctly parsed.

Since 1.6


struct GstJpegQuantTable

struct GstJpegQuantTable {
  guint8 quant_precision;
  guint16 quant_table[GST_JPEG_MAX_QUANT_ELEMENTS];
  gboolean valid;
};

Quantization table.

guint8 quant_precision;

Quantization table element precision (Pq)

guint16 quant_table[GST_JPEG_MAX_QUANT_ELEMENTS];

Quantization table elements (Qk)

gboolean valid;

If the quantization table is valid, which means it has already been parsed

Since 1.6


gst_jpeg_segment_parse_quantization_table ()

gboolean            gst_jpeg_segment_parse_quantization_table
                                                        (const GstJpegSegment *segment,
                                                         GstJpegQuantTables *quant_tables);

Parses the JPEG quantization table structure members from segment.

The caller must make sure there is enough data for the whole segment available.

Note: quant_tables represents the complete set of possible quantization tables. However, the parser will only write to the quantization table specified by the table destination identifier (Tq). While doing so, the valid flag of the specified quantization table will also be set to TRUE.

segment :

the JPEG segment

quant_tables :

The GstJpegQuantTables structure to fill in. [out]

Returns :

TRUE if the quantization table was correctly parsed.

Since 1.6


gst_jpeg_segment_parse_restart_interval ()

gboolean            gst_jpeg_segment_parse_restart_interval
                                                        (const GstJpegSegment *segment,
                                                         guint *interval);

The caller must make sure there is enough data for the whole segment available.

segment :

the JPEG segment

interval :

The parsed restart interval value. [out]

Returns :

TRUE if the restart interval value was correctly parsed.

Since 1.6


gst_jpeg_get_default_quantization_tables ()

void                gst_jpeg_get_default_quantization_tables
                                                        (GstJpegQuantTables *quant_tables);

gst_jpeg_get_default_huffman_tables ()

void                gst_jpeg_get_default_huffman_tables (GstJpegHuffmanTables *huff_tables);

Fills in huf_tables with the default AC/DC Huffman tables, as specified by the JPEG standard.

huf_tables :

The default DC/AC Huffman tables to fill in. [out]

Since 1.6