gst-libs/gst/codecparsers/gstjpegparser.h

   1 /*
   2  *  gstjpegparser.h - JPEG parser
   3  *
   4  *  Copyright (C) 2011-2012 Intel Corporation
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public License
   8  *  as published by the Free Software Foundation; either version 2.1
   9  *  of the License, or (at your option) any later version.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free
  18  *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19  *  Boston, MA 02110-1301 USA
  20  */
  21
  22 #ifndef GST_JPEG_PARSER_H
  23 #define GST_JPEG_PARSER_H
  24
  25 #ifndef GST_USE_UNSTABLE_API
  26 #  warning "The JPEG parsing library is unstable API and may change in future."
  27 #  warning "You can define GST_USE_UNSTABLE_API to avoid this warning."
  28 #endif
  29
  30 #include <gst/gst.h>
  31
  32 G_BEGIN_DECLS
  33
  34 /**
  35  * GST_JPEG_MAX_FRAME_COMPONENTS:
  36  *
  37  * Maximum number of image components in a frame (Nf).
  38  */
  39 #define GST_JPEG_MAX_FRAME_COMPONENTS   256
  40
  41 /**
  42  * GST_JPEG_MAX_SCAN_COMPONENTS:
  43  *
  44  * Maximum number of image components in a scan (Ns).
  45  */
  46 #define GST_JPEG_MAX_SCAN_COMPONENTS    4
  47
  48 /**
  49  * GST_JPEG_MAX_QUANT_ELEMENTS:
  50  *
  51  * Number of elements in the quantization table.
  52  */
  53 #define GST_JPEG_MAX_QUANT_ELEMENTS     64
  54
  55 typedef struct _GstJpegQuantTable       GstJpegQuantTable;
  56 typedef struct _GstJpegQuantTables      GstJpegQuantTables;
  57 typedef struct _GstJpegHuffmanTable     GstJpegHuffmanTable;
  58 typedef struct _GstJpegHuffmanTables    GstJpegHuffmanTables;
  59 typedef struct _GstJpegScanComponent    GstJpegScanComponent;
  60 typedef struct _GstJpegScanHdr          GstJpegScanHdr;
  61 typedef struct _GstJpegFrameComponent   GstJpegFrameComponent;
  62 typedef struct _GstJpegFrameHdr         GstJpegFrameHdr;
  63 typedef struct _GstJpegMarkerSegment    GstJpegMarkerSegment;
  64
  65 /**
  66  * GstJpegMarkerCode:
  67  * @GST_JPEG_MARKER_SOF_MIN: Start of frame min marker code
  68  * @GST_JPEG_MARKER_SOF_MAX: Start of frame max marker code
  69  * @GST_JPEG_MARKER_DHT: Huffman tabler marker code
  70  * @GST_JPEG_MARKER_DAC: Arithmetic coding marker code
  71  * @GST_JPEG_MARKER_RST_MIN: Restart interval min marker code
  72  * @GST_JPEG_MARKER_RST_MAX: Restart interval max marker code
  73  * @GST_JPEG_MARKER_SOI: Start of image marker code
  74  * @GST_JPEG_MARKER_EOI: End of image marker code
  75  * @GST_JPEG_MARKER_SOS: Start of scan marker code
  76  * @GST_JPEG_MARKER_DQT: Define quantization table marker code
  77  * @GST_JPEG_MARKER_DNL: Define number of lines marker code
  78  * @GST_JPEG_MARKER_DRI: Define restart interval marker code
  79  * @GST_JPEG_MARKER_APP_MIN: Application segment min marker code
  80  * @GST_JPEG_MARKER_APP_MAX: Application segment max marker code
  81  * @GST_JPEG_MARKER_COM: Comment marker code
  82  *
  83  * Indicates the type of JPEG segment.
  84  */
  85 typedef enum {
  86   GST_JPEG_MARKER_SOF_MIN       = 0xC0,
  87   GST_JPEG_MARKER_SOF_MAX       = 0xCF,
  88   GST_JPEG_MARKER_DHT           = 0xC4,
  89   GST_JPEG_MARKER_DAC           = 0xCC,
  90   GST_JPEG_MARKER_RST_MIN       = 0xD0,
  91   GST_JPEG_MARKER_RST_MAX       = 0xD7,
  92   GST_JPEG_MARKER_SOI           = 0xD8,
  93   GST_JPEG_MARKER_EOI           = 0xD9,
  94   GST_JPEG_MARKER_SOS           = 0xDA,
  95   GST_JPEG_MARKER_DQT           = 0xDB,
  96   GST_JPEG_MARKER_DNL           = 0xDC,
  97   GST_JPEG_MARKER_DRI           = 0xDD,
  98   GST_JPEG_MARKER_APP_MIN       = 0xE0,
  99   GST_JPEG_MARKER_APP_MAX       = 0xEF,
 100   GST_JPEG_MARKER_COM           = 0xFE,
 101 } GstJpegMarkerCode;
 102
 103 /**
 104  * GstJpegProfile:
 105  * @GST_JPEG_PROFILE_BASELINE: Baseline DCT
 106  * @GST_JPEG_PROFILE_EXTENDED: Extended sequential DCT
 107  * @GST_JPEG_PROFILE_PROGRESSIVE: Progressive DCT
 108  * @GST_JPEG_PROFILE_LOSSLESS: Lossless (sequential)
 109  *
 110  * JPEG encoding processes.
 111  */
 112 typedef enum {
 113   GST_JPEG_PROFILE_BASELINE     = 0x00,
 114   GST_JPEG_PROFILE_EXTENDED     = 0x01,
 115   GST_JPEG_PROFILE_PROGRESSIVE  = 0x02,
 116   GST_JPEG_PROFILE_LOSSLESS     = 0x03,
 117 } GstJpegProfile;
 118
 119 /**
 120  * GstJpegEntropyCodingMode:
 121  * @GST_JPEG_ENTROPY_CODING_HUFFMAN: Huffman coding
 122  * @GST_JPEG_ENTROPY_CODING_ARITHMETIC: arithmetic coding
 123  *
 124  * JPEG entropy coding mode.
 125  */
 126 typedef enum {
 127   GST_JPEG_ENTROPY_CODING_HUFFMAN       = 0x00,
 128   GST_JPEG_ENTROPY_CODING_ARITHMETIC    = 0x08
 129 } GstJpegEntropyCodingMode;
 130
 131 /**
 132  * GstJpegQuantTable:
 133  * @quant_precision: Quantization table element precision (Pq)
 134  * @quant_table: Quantization table elements (Qk)
 135  * @valid: If the quantization table is valid, which means it has
 136  *   already been parsed
 137  *
 138  * Quantization table.
 139  */
 140 struct _GstJpegQuantTable
 141 {
 142   guint8 quant_precision;
 143   guint16 quant_table[GST_JPEG_MAX_QUANT_ELEMENTS];
 144   gboolean valid;
 145 };
 146
 147 /**
 148  * GstJpegQuantTables:
 149  * @quant_tables: All quantization tables
 150  *
 151  * Helper data structure that holds all quantization tables used to
 152  * decode an image.
 153  */
 154 struct _GstJpegQuantTables
 155 {
 156   GstJpegQuantTable quant_tables[GST_JPEG_MAX_SCAN_COMPONENTS];
 157 };
 158
 159 /**
 160  * GstJpegHuffmanTable:
 161  * @huf_bits: Number of Huffman codes of length i + 1 (Li)
 162  * @huf_vales: Value associated with each Huffman code (Vij)
 163  * @valid: If the Huffman table is valid, which means it has already
 164  *   been parsed
 165  *
 166  * Huffman table.
 167  */
 168 struct _GstJpegHuffmanTable
 169 {
 170   guint8 huf_bits[16];
 171   guint8 huf_values[256];
 172   gboolean valid;
 173 };
 174
 175 /**
 176  * GstJpegHuffmanTables:
 177  * @dc_tables: DC Huffman tables
 178  * @ac_tables: AC Huffman tables
 179  *
 180  * Helper data structure that holds all AC/DC Huffman tables used to
 181  * decode an image.
 182  */
 183 struct _GstJpegHuffmanTables
 184 {
 185   GstJpegHuffmanTable dc_tables[GST_JPEG_MAX_SCAN_COMPONENTS];
 186   GstJpegHuffmanTable ac_tables[GST_JPEG_MAX_SCAN_COMPONENTS];
 187 };
 188
 189 /**
 190  * GstJpegScanComponent:
 191  * @component_selector: Scan component selector (Csj)
 192  * @dc_selector: DC entropy coding table destination selector (Tdj)
 193  * @ac_selector: AC entropy coding table destination selector (Taj)
 194
 195  * Component-specification parameters.
 196  */
 197 struct _GstJpegScanComponent
 198 {
 199     guint8 component_selector;          /* 0 .. 255     */
 200     guint8 dc_selector;                 /* 0 .. 3       */
 201     guint8 ac_selector;                 /* 0 .. 3       */
 202 };
 203
 204 /**
 205  * GstJpegScanHdr:
 206  * @num_components: Number of image components in scan (Ns)
 207  * @components: Image components
 208  *
 209  * Scan header.
 210  */
 211 struct _GstJpegScanHdr
 212 {
 213   guint8 num_components;                /* 1 .. 4       */
 214   GstJpegScanComponent components[GST_JPEG_MAX_SCAN_COMPONENTS];
 215 };
 216
 217 /**
 218  * GstJpegFrameComponent:
 219  * @identifier: Component identifier (Ci)
 220  * @horizontal_factor: Horizontal sampling factor (Hi)
 221  * @vertical_factor: Vertical sampling factor (Vi)
 222  * @quant_table_selector: Quantization table destination selector (Tqi)
 223  *
 224  * Component-specification parameters.
 225  */
 226 struct _GstJpegFrameComponent
 227 {
 228   guint8 identifier;                    /* 0 .. 255     */
 229   guint8 horizontal_factor;             /* 1 .. 4       */
 230   guint8 vertical_factor;               /* 1 .. 4       */
 231   guint8 quant_table_selector;          /* 0 .. 3       */
 232 };
 233
 234 /**
 235  * GstJpegFrameHdr:
 236  * @sample_precision: Sample precision (P)
 237  * @height: Number of lines (Y)
 238  * @width: Number of samples per line (X)
 239  * @num_components: Number of image components in frame (Nf)
 240  * @components: Image components
 241  * @restart_interval: Number of MCU in the restart interval (Ri)
 242  *
 243  * Frame header.
 244  */
 245 struct _GstJpegFrameHdr
 246 {
 247   guint8 sample_precision;              /* 2 .. 16      */
 248   guint16 width;                        /* 1 .. 65535   */
 249   guint16 height;                       /* 0 .. 65535   */
 250   guint8 num_components;                /* 1 .. 255     */
 251   GstJpegFrameComponent components[GST_JPEG_MAX_FRAME_COMPONENTS];
 252 };
 253
 254 /**
 255  * GstJpegMarkerSegment:
 256  * @type: The type of the segment that starts at @offset
 257  * @offset: The offset to the segment start in bytes. This is the
 258  *   exact start of the segment, no marker code included
 259  * @size: The size in bytes of the segment, or -1 if the end was not
 260  *   found. It is the exact size of the segment, no marker code included
 261  *
 262  * A structure that contains the type of a segment, its offset and its size.
 263  */
 264 struct _GstJpegMarkerSegment
 265 {
 266   guint8 marker;
 267   guint offset;
 268   gint size;
 269 };
 270
 271 /**
 272  * gst_jpeg_scan_for_marker_code:
 273  * @data: The data to parse
 274  * @size: The size of @data
 275  * @offset: The offset from which to start parsing
 276  *
 277  * Scans the JPEG bitstream contained in @data for the next marker
 278  * code. If found, the function returns an offset to the marker code,
 279  * including the 0xff prefix code but excluding any extra fill bytes.
 280  *
 281  * Returns: offset to the marker code if found, or -1 if not found.
 282  */
 283 gint            gst_jpeg_scan_for_marker_code   (const guint8 * data,
 284                                                  gsize size,
 285                                                  guint offset);
 286
 287 /**
 288  * gst_jpeg_parse:
 289  * @data: The data to parse
 290  * @size: The size of @data
 291  * @offset: The offset from which to start parsing
 292  *
 293  * Parses the JPEG bitstream contained in @data, and returns the
 294  * detected segment as a #GstJpegMarkerSegment.
 295  *
 296  * Returns: TRUE if a packet start code was found.
 297  */
 298 gboolean        gst_jpeg_parse                  (GstJpegMarkerSegment * seg,
 299                                                  const guint8 * data,
 300                                                  gsize size,
 301                                                  guint offset);
 302
 303 /**
 304  * gst_jpeg_parse_frame_hdr:
 305  * @hdr: (out): The #GstJpegFrameHdr structure to fill in
 306  * @data: The data from which to parse the frame header
 307  * @size: The size of @data
 308  * @offset: The offset in bytes from which to start parsing @data
 309  *
 310  * Parses the @hdr JPEG frame header structure members from @data.
 311  *
 312  * Returns: TRUE if the frame header was correctly parsed.
 313  */
 314 gboolean        gst_jpeg_parse_frame_hdr        (GstJpegFrameHdr * hdr,
 315                                                  const guint8 * data,
 316                                                  gsize size,
 317                                                  guint offset);
 318
 319 /**
 320  * gst_jpeg_parse_scan_hdr:
 321  * @hdr: (out): The #GstJpegScanHdr structure to fill in
 322  * @data: The data from which to parse the scan header
 323  * @size: The size of @data
 324  * @offset: The offset in bytes from which to start parsing @data
 325  *
 326  * Parses the @hdr JPEG scan header structure members from @data.
 327  *
 328  * Returns: TRUE if the scan header was correctly parsed
 329  */
 330 gboolean        gst_jpeg_parse_scan_hdr         (GstJpegScanHdr * hdr,
 331                                                  const guint8 * data,
 332                                                  gsize size,
 333                                                  guint offset);
 334
 335 /**
 336  * gst_jpeg_parse_quantization_table:
 337  * @quant_tables: (out): The #GstJpegQuantizationTable structure to fill in
 338  * @num_quant_tables: The number of allocated quantization tables in @quant_tables
 339  * @data: The data from which to parse the quantization table
 340  * @size: The size of @data
 341  * @offset: The offset in bytes from which to start parsing @data
 342  *
 343  * Parses the JPEG quantization table structure members from @data.
 344  *
 345  * Note: @quant_tables represents the complete set of possible
 346  * quantization tables. However, the parser will only write to the
 347  * quantization table specified by the table destination identifier
 348  * (Tq). While doing so, the @valid flag of the specified quantization
 349  * table will also be set to %TRUE.
 350  *
 351  * Returns: TRUE if the quantization table was correctly parsed.
 352  */
 353 gboolean        gst_jpeg_parse_quant_table      (GstJpegQuantTables *quant_tables,
 354                                                  const guint8 * data,
 355                                                  gsize size,
 356                                                  guint offset);
 357
 358 /**
 359  * gst_jpeg_parse_huffman_table:
 360  * @huf_tables: (out): The #GstJpegHuffmanTable structure to fill in
 361  * @data: The data from which to parse the Huffman table
 362  * @size: The size of @data
 363  * @offset: The offset in bytes from which to start parsing @data
 364  *
 365  * Parses the JPEG Huffman table structure members from @data.
 366  *
 367  * Note: @huf_tables represents the complete set of possible Huffman
 368  * tables. However, the parser will only write to the Huffman table
 369  * specified by the table destination identifier (Th). While doing so,
 370  * the @valid flag of the specified Huffman table will also be set to
 371  * %TRUE;
 372  *
 373  * Returns: TRUE if the Huffman table was correctly parsed.
 374  */
 375 gboolean        gst_jpeg_parse_huffman_table    (GstJpegHuffmanTables *huf_tables,
 376                                                  const guint8 * data,
 377                                                  gsize size,
 378                                                  guint offset);
 379
 380 /**
 381  * gst_jpeg_parse_restart_interval:
 382  * @interval: (out): The parsed restart interval value
 383  * @data: The data from which to parse the restart interval specification
 384  * @size: The size of @data
 385  * @offset: The offset in bytes from which to start parsing @data
 386  *
 387  * Returns: TRUE if the restart interval value was correctly parsed.
 388  */
 389 gboolean        gst_jpeg_parse_restart_interval (guint * interval,
 390                                                  const guint8 * data,
 391                                                  gsize size,
 392                                                  guint offset);
 393
 394 /**
 395  * gst_jpeg_get_default_huffman_tables:
 396  * @huf_tables: (out): The default DC/AC Huffman tables to fill in
 397  *
 398  * Fills in @huf_tables with the default AC/DC Huffman tables, as
 399  * specified by the JPEG standard.
 400  */
 401 void gst_jpeg_get_default_huffman_tables (GstJpegHuffmanTables *huf_tables);
 402
 403 /**
 404  * gst_jpeg_get_default_quantization_table:
 405  * @quant_tables: (out): The default luma/chroma quant-tables in zigzag mode
 406  *
 407  * Fills in @quant_tables with the default quantization tables, as
 408  * specified by the JPEG standard.
 409  */
 410 void gst_jpeg_get_default_quantization_tables (GstJpegQuantTables *quant_tables);
 411
 412 G_END_DECLS
 413
 414 #endif /* GST_JPEG_PARSER_H */