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
36extern "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. */
48typedef 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
81typedef int (*VAEncBitstreamFlushFunc)(
82    VAEncBitstream *bs,
83    unsigned char  *buffer,
84    unsigned int    buffer_size
85);
86
87/** \brief Bitstream writer attribute types. */
88typedef 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. */
106typedef 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 */
126VAEncBitstream *
127va_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 */
134void
135va_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 */
148int
149va_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 */
162int
163va_enc_bitstream_write_si(VAEncBitstream *bs, int value, int length);
164
165#if 0
166/* XXX: expose such API? */
167int
168va_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 */
181int
182va_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 */
196int
197va_enc_bitstream_flush(VAEncBitstream *bs);
198
199/**@}*/
200
201#ifdef __cplusplus
202}
203#endif
204
205#endif /* VA_ENC_H */
206