Home | History | Annotate | Download | only in va 
      1 /*
      2  * Copyright (c) 2007-2011 Intel Corporation. All Rights Reserved.
      3  *
      4  * Permission is hereby granted, free of charge, to any person obtaining a
      5  * copy of this software and associated documentation files (the
      6  * "Software"), to deal in the Software without restriction, including
      7  * without limitation the rights to use, copy, modify, merge, publish,
      8  * distribute, sub license, and/or sell copies of the Software, and to
      9  * permit persons to whom the Software is furnished to do so, subject to
     10  * the following conditions:
     11  *
     12  * The above copyright notice and this permission notice (including the
     13  * next paragraph) shall be included in all copies or substantial portions
     14  * of the Software.
     15  *
     16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
     17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
     18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
     19  * IN NO EVENT SHALL INTEL AND/OR ITS SUPPLIERS BE LIABLE FOR
     20  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
     21  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
     22  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
     23  */
     24 
     25 /**
     26  * \file va_enc.h
     27  * \brief The Core encoding API
     28  *
     29  * This file contains the \ref api_enc_core "Core encoding API".
     30  */
     31 
     32 #ifndef VA_ENC_H
     33 #define VA_ENC_H
     34 
     35 #ifdef __cplusplus
     36 extern "C" {
     37 #endif
     38 
     39 #include <va/va.h>
     40 
     41 /**
     42  * \defgroup api_enc_core Core encoding API
     43  *
     44  * @{
     45  */
     46 
     47 /** \brief Abstract representation of a bitstream writer. */
     48 typedef struct _VAEncBitstream VAEncBitstream;
     49 
     50 /**
     51  * @name Picture flags
     52  *
     53  * Those flags flags are meant to signal when a picture marks the end
     54  * of a sequence, a stream, or even both at once.
     55  *
     56  * @{
     57  */
     58 /**
     59  * \brief Marks the last picture in the sequence.
     60  *
     61  */
     62 #define VA_ENC_LAST_PICTURE_EOSEQ       0x01
     63 /**
     64  * \brief Marks the last picture in the stream.
     65  *
     66  */
     67 #define VA_ENC_LAST_PICTURE_EOSTREAM    0x02
     68 /**@}*/
     69 
     70 
     71 /** @name The set of all possible error codes */
     72 /**@{*/
     73 /** \brief An invalid bitstream writer handle was supplied. */
     74 #define VA_ENC_STATUS_ERROR_INVALID_BITSTREAM_WRITER    (-1)
     75 /** \brief An invalid/unsupported parameter value was supplied. */
     76 #define VA_ENC_STATUS_ERROR_INVALID_VALUE               (-2)
     77 /** \brief A buffer overflow has occurred. */
     78 #define VA_ENC_STATUS_ERROR_BUFFER_OVERFLOW             (-3)
     79 /**@}*/
     80 
     81 typedef int (*VAEncBitstreamFlushFunc)(
     82     VAEncBitstream *bs,
     83     unsigned char  *buffer,
     84     unsigned int    buffer_size
     85 );
     86 
     87 /** \brief Bitstream writer attribute types. */
     88 typedef enum {
     89     /**
     90      * \brief User-provided buffer to hold output bitstream (pointer).
     91      *
     92      * If this attribute is provided, then \c VAencBitstreamAttribBufferSize
     93      * shall also be supplied or va_enc_bitstream_new() will ignore that
     94      * attribute and allocate its own buffer.
     95      */
     96     VAEncBitstreamAttribBuffer          = 1,
     97     /** \brief Size of the user-provided buffer (integer). */
     98     VAEncBitstreamAttribBufferSize      = 2,
     99     /** \brief User-provided \c flush() callback (pointer-to-function). */
    100     VAEncBitstreamAttribFlushFunc       = 3,
    101     /** \brief Placeholder for codec-specific attributes. */
    102     VAEncBitstreamAttribMiscMask        = 0x80000000
    103 } VAEncBitstreamAttribType;
    104 
    105 /** \brief Bitstream writer attribute value. */
    106 typedef struct {
    107     /** \brief Attribute type (#VAEncBitstreamAttribType). */
    108     VAEncBitstreamAttribType    type;
    109     /** \brief Attribute value (#VAGenericValue). */
    110     VAGenericValue              value;
    111 } VAEncBitstreamAttrib;
    112 
    113 /**
    114  * \brief Allocates a new bitstream writer.
    115  *
    116  * Allocates a new bitstream writer. By default, libva allocates and
    117  * maintains its own buffer. However, the user can pass down his own
    118  * buffer with the \c VAEncBitstreamAttribBuffer attribute, along with
    119  * the size of that buffer with the \c VAEncBitstreamAttribBufferSize
    120  * attribute.
    121  *
    122  * @param[in] attribs       the optional attributes, or NULL
    123  * @param[in] num_attribs   the number of attributes available in \c attribs
    124  * @return a new #VAEncBitstream, or NULL if an error occurred
    125  */
    126 VAEncBitstream *
    127 va_enc_bitstream_new(VAEncBitstreamAttrib *attribs, unsigned int num_attribs);
    128 
    129 /**
    130  * \brief Destroys a bitstream writer.
    131  *
    132  * @param[in] bs            the bitstream writer to destroy
    133  */
    134 void
    135 va_enc_bitstream_destroy(VAEncBitstream *bs);
    136 
    137 /**
    138  * \brief Writes an unsigned integer.
    139  *
    140  * Writes an unsigned int value of the specified length in bits. The
    141  * value is implicitly zero-extended to the number of specified bits.
    142  *
    143  * @param[in] bs            the bitstream writer
    144  * @param[in] value         the unsigned int value to write
    145  * @param[in] length        the length (in bits) of the value
    146  * @return the number of bits written, or a negative value to indicate an error
    147  */
    148 int
    149 va_enc_bitstream_write_ui(VAEncBitstream *bs, unsigned int value, int length);
    150 
    151 /**
    152  * \brief Writes a signed integer.
    153  *
    154  * Writes a signed int value of the specified length in bits. The
    155  * value is implicitly sign-extended to the number of specified bits.
    156  *
    157  * @param[in] bs            the bitstream writer
    158  * @param[in] value         the signed int value to write
    159  * @param[in] length        the length (in bits) of the value
    160  * @return the number of bits written, or a negative value to indicate an error
    161  */
    162 int
    163 va_enc_bitstream_write_si(VAEncBitstream *bs, int value, int length);
    164 
    165 #if 0
    166 /* XXX: expose such API? */
    167 int
    168 va_enc_bitstream_skip(VAEncBitstream *bs, unsigned int length);
    169 #endif
    170 
    171 /**
    172  * \brief Byte aligns the bitstream.
    173  *
    174  * Align the bitstream to next byte boundary, while filling in bits
    175  * with the specified value (0 or 1).
    176  *
    177  * @param[in] bs            the bitstream writer
    178  * @param[in] value         the bit filler value (0 or 1)
    179  * @return the number of bits written, or a negative value to indicate an error
    180  */
    181 int
    182 va_enc_bitstream_align(VAEncBitstream *bs, unsigned int value);
    183 
    184 /**
    185  * \brief Flushes the bitstream.
    186  *
    187  * Flushes the bitstream, while padding with zeroe's up to the next
    188  * byte boundary. This functions resets the bitstream writer to its
    189  * initial state. If the user provided a flush function through the
    190  * \c VAEncBitstreamFlushFunc attribute, then his callback will be
    191  * called.
    192  *
    193  * @param[in] bs            the bitstream writer
    194  * @return the number of bytes written, or a negative value to indicate an error
    195  */
    196 int
    197 va_enc_bitstream_flush(VAEncBitstream *bs);
    198 
    199 /**@}*/
    200 
    201 #ifdef __cplusplus
    202 }
    203 #endif
    204 
    205 #endif /* VA_ENC_H */
    206