va/va_enc.h

   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 */