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 /**
  40  * \defgroup api_enc_core Core encoding API
  41  *
  42  * @{
  43  */
  44
  45 /** \brief Abstract representation of a bitstream writer. */
  46 typedef struct _VAEncBitstream VAEncBitstream;
  47
  48 /** @name The set of all possible error codes */
  49 /**@{*/
  50 /** \brief An invalid bitstream writer handle was supplied. */
  51 #define VA_ENC_STATUS_ERROR_INVALID_BITSTREAM_WRITER    (-1)
  52 /** \brief An invalid/unsupported parameter value was supplied. */
  53 #define VA_ENC_STATUS_ERROR_INVALID_VALUE               (-2)
  54 /** \brief A buffer overflow has occurred. */
  55 #define VA_ENC_STATUS_ERROR_BUFFER_OVERFLOW             (-3)
  56 /**@}*/
  57
  58 typedef int (*VAEncBitstreamFlushFunc)(
  59     VAEncBitstream *bs,
  60     unsigned char  *buffer,
  61     unsigned int    buffer_size
  62 );
  63
  64 /** \brief Bitstream writer attribute types. */
  65 typedef enum {
  66     /**
  67      * \brief User-provided buffer to hold output bitstream (pointer).
  68      *
  69      * If this attribute is provided, then \c VAencBitstreamAttribBufferSize
  70      * shall also be supplied or va_enc_bitstream_new() will ignore that
  71      * attribute and allocate its own buffer.
  72      */
  73     VAEncBitstreamAttribBuffer          = 1,
  74     /** \brief Size of the user-provided buffer (integer). */
  75     VAEncBitstreamAttribBufferSize      = 2,
  76     /** \brief User-provided \c flush() callback (pointer-to-function). */
  77     VAEncBitstreamAttribFlushFunc       = 3,
  78     /** \brief Placeholder for codec-specific attributes. */
  79     VAEncBitstreamAttribMiscMask        = 0x80000000
  80 } VAEncBitstreamAttribType;
  81
  82 /** \brief Bitstream writer attribute value. */
  83 typedef struct {
  84     /** \brief Attribute type (#VAEncBitstreamAttribType). */
  85     VAEncBitstreamAttribType    type;
  86     /** \brief Attribute value (#VAGenericValue). */
  87     VAGenericValue              value;
  88 } VAEncBitstreamAttrib;
  89
  90 /**
  91  * \brief Allocates a new bitstream writer.
  92  *
  93  * Allocates a new bitstream writer. By default, libva allocates and
  94  * maintains its own buffer. However, the user can pass down his own
  95  * buffer with the \c VAEncBitstreamAttribBuffer attribute, along with
  96  * the size of that buffer with the \c VAEncBitstreamAttribBufferSize
  97  * attribute.
  98  *
  99  * @param[in] attribs       the optional attributes, or NULL
 100  * @param[in] num_attribs   the number of attributes available in \c attribs
 101  * @return a new #VAEncBitstream, or NULL if an error occurred
 102  */
 103 VAEncBitstream *
 104 va_enc_bitstream_new(VAEncBitstreamAttrib *attribs, unsigned int num_attribs);
 105
 106 /**
 107  * \brief Destroys a bitstream writer.
 108  *
 109  * @param[in] bs            the bitstream writer to destroy
 110  */
 111 void
 112 va_enc_bitstream_destroy(VAEncBitstream *bs);
 113
 114 /**
 115  * \brief Writes an unsigned integer.
 116  *
 117  * Writes an unsigned int value of the specified length in bits. The
 118  * value is implicitly zero-extended to the number of specified bits.
 119  *
 120  * @param[in] bs            the bitstream writer
 121  * @param[in] value         the unsigned int value to write
 122  * @param[in] length        the length (in bits) of the value
 123  * @return the number of bits written, or a negative value to indicate an error
 124  */
 125 int
 126 va_enc_bitstream_write_ui(VAEncBitstream *bs, unsigned int value, int length);
 127
 128 /**
 129  * \brief Writes a signed integer.
 130  *
 131  * Writes a signed int value of the specified length in bits. The
 132  * value is implicitly sign-extended to the number of specified bits.
 133  *
 134  * @param[in] bs            the bitstream writer
 135  * @param[in] value         the signed int value to write
 136  * @param[in] length        the length (in bits) of the value
 137  * @return the number of bits written, or a negative value to indicate an error
 138  */
 139 int
 140 va_enc_bitstream_write_si(VAEncBitstream *bs, int value, int length);
 141
 142 #if 0
 143 /* XXX: expose such API? */
 144 int
 145 va_enc_bitstream_skip(VAEncBitstream *bs, unsigned int length);
 146 #endif
 147
 148 /**
 149  * \brief Byte aligns the bitstream.
 150  *
 151  * Align the bitstream to next byte boundary, while filling in bits
 152  * with the specified value (0 or 1).
 153  *
 154  * @param[in] bs            the bitstream writer
 155  * @param[in] value         the bit filler value (0 or 1)
 156  * @return the number of bits written, or a negative value to indicate an error
 157  */
 158 int
 159 va_enc_bitstream_align(VAEncBitstream *bs, unsigned int value);
 160
 161 /**
 162  * \brief Flushes the bitstream.
 163  *
 164  * Flushes the bitstream, while padding with zeroe's up to the next
 165  * byte boundary. This functions resets the bitstream writer to its
 166  * initial state. If the user provided a flush function through the
 167  * \c VAEncBitstreamFlushFunc attribute, then his callback will be
 168  * called.
 169  *
 170  * @param[in] bs            the bitstream writer
 171  * @return the number of bytes written, or a negative value to indicate an error
 172  */
 173 int
 174 va_enc_bitstream_flush(VAEncBitstream *bs);
 175
 176 /**@}*/
 177
 178 #ifdef __cplusplus
 179 }
 180 #endif
 181
 182 #endif /* VA_ENC_H */