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