1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/*
18 * This file defines an NDK API.
19 * Do not remove methods.
20 * Do not change method signatures.
21 * Do not change the value of constants.
22 * Do not change the size of any of the classes defined in here.
23 * Do not reference types that are not part of the NDK.
24 * Do not #include files that aren't part of the NDK.
25 */
26
27#ifndef _NDK_MEDIA_CODEC_H
28#define _NDK_MEDIA_CODEC_H
29
30#include <sys/cdefs.h>
31
32#include "NdkMediaCrypto.h"
33#include "NdkMediaError.h"
34#include "NdkMediaFormat.h"
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40struct ANativeWindow;
41
42#if __ANDROID_API__ >= 21
43
44struct AMediaCodec;
45typedef struct AMediaCodec AMediaCodec;
46
47struct AMediaCodecBufferInfo {
48    int32_t offset;
49    int32_t size;
50    int64_t presentationTimeUs;
51    uint32_t flags;
52};
53typedef struct AMediaCodecBufferInfo AMediaCodecBufferInfo;
54typedef struct AMediaCodecCryptoInfo AMediaCodecCryptoInfo;
55
56enum {
57    AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM = 4,
58    AMEDIACODEC_CONFIGURE_FLAG_ENCODE = 1,
59    AMEDIACODEC_INFO_OUTPUT_BUFFERS_CHANGED = -3,
60    AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED = -2,
61    AMEDIACODEC_INFO_TRY_AGAIN_LATER = -1
62};
63
64/**
65 * Create codec by name. Use this if you know the exact codec you want to use.
66 * When configuring, you will need to specify whether to use the codec as an
67 * encoder or decoder.
68 */
69AMediaCodec* AMediaCodec_createCodecByName(const char *name);
70
71/**
72 * Create codec by mime type. Most applications will use this, specifying a
73 * mime type obtained from media extractor.
74 */
75AMediaCodec* AMediaCodec_createDecoderByType(const char *mime_type);
76
77/**
78 * Create encoder by name.
79 */
80AMediaCodec* AMediaCodec_createEncoderByType(const char *mime_type);
81
82/**
83 * delete the codec and free its resources
84 */
85media_status_t AMediaCodec_delete(AMediaCodec*);
86
87/**
88 * Configure the codec. For decoding you would typically get the format from an extractor.
89 */
90media_status_t AMediaCodec_configure(
91        AMediaCodec*,
92        const AMediaFormat* format,
93        ANativeWindow* surface,
94        AMediaCrypto *crypto,
95        uint32_t flags);
96
97/**
98 * Start the codec. A codec must be configured before it can be started, and must be started
99 * before buffers can be sent to it.
100 */
101media_status_t AMediaCodec_start(AMediaCodec*);
102
103/**
104 * Stop the codec.
105 */
106media_status_t AMediaCodec_stop(AMediaCodec*);
107
108/*
109 * Flush the codec's input and output. All indices previously returned from calls to
110 * AMediaCodec_dequeueInputBuffer and AMediaCodec_dequeueOutputBuffer become invalid.
111 */
112media_status_t AMediaCodec_flush(AMediaCodec*);
113
114/**
115 * Get an input buffer. The specified buffer index must have been previously obtained from
116 * dequeueInputBuffer, and not yet queued.
117 */
118uint8_t* AMediaCodec_getInputBuffer(AMediaCodec*, size_t idx, size_t *out_size);
119
120/**
121 * Get an output buffer. The specified buffer index must have been previously obtained from
122 * dequeueOutputBuffer, and not yet queued.
123 */
124uint8_t* AMediaCodec_getOutputBuffer(AMediaCodec*, size_t idx, size_t *out_size);
125
126/**
127 * Get the index of the next available input buffer. An app will typically use this with
128 * getInputBuffer() to get a pointer to the buffer, then copy the data to be encoded or decoded
129 * into the buffer before passing it to the codec.
130 */
131ssize_t AMediaCodec_dequeueInputBuffer(AMediaCodec*, int64_t timeoutUs);
132
133/**
134 * Send the specified buffer to the codec for processing.
135 */
136media_status_t AMediaCodec_queueInputBuffer(AMediaCodec*,
137        size_t idx, off_t offset, size_t size, uint64_t time, uint32_t flags);
138
139/**
140 * Send the specified buffer to the codec for processing.
141 */
142media_status_t AMediaCodec_queueSecureInputBuffer(AMediaCodec*,
143        size_t idx, off_t offset, AMediaCodecCryptoInfo*, uint64_t time, uint32_t flags);
144
145/**
146 * Get the index of the next available buffer of processed data.
147 */
148ssize_t AMediaCodec_dequeueOutputBuffer(AMediaCodec*, AMediaCodecBufferInfo *info,
149        int64_t timeoutUs);
150AMediaFormat* AMediaCodec_getOutputFormat(AMediaCodec*);
151
152/**
153 * If you are done with a buffer, use this call to return the buffer to
154 * the codec. If you previously specified a surface when configuring this
155 * video decoder you can optionally render the buffer.
156 */
157media_status_t AMediaCodec_releaseOutputBuffer(AMediaCodec*, size_t idx, bool render);
158
159/**
160 * Dynamically sets the output surface of a codec.
161 *
162 *  This can only be used if the codec was configured with an output surface.  The
163 *  new output surface should have a compatible usage type to the original output surface.
164 *  E.g. codecs may not support switching from a SurfaceTexture (GPU readable) output
165 *  to ImageReader (software readable) output.
166 *
167 * For more details, see the Java documentation for MediaCodec.setOutputSurface.
168 */
169media_status_t AMediaCodec_setOutputSurface(AMediaCodec*, ANativeWindow* surface);
170
171/**
172 * If you are done with a buffer, use this call to update its surface timestamp
173 * and return it to the codec to render it on the output surface. If you
174 * have not specified an output surface when configuring this video codec,
175 * this call will simply return the buffer to the codec.
176 *
177 * For more details, see the Java documentation for MediaCodec.releaseOutputBuffer.
178 */
179media_status_t AMediaCodec_releaseOutputBufferAtTime(
180        AMediaCodec *mData, size_t idx, int64_t timestampNs);
181
182/**
183 * Creates a Surface that can be used as the input to encoder, in place of input buffers
184 *
185 * This can only be called after the codec has been configured via
186 * AMediaCodec_configure(..); and before AMediaCodec_start() has been called.
187 *
188 * The application is responsible for releasing the surface by calling
189 * ANativeWindow_release() when done.
190 *
191 * For more details, see the Java documentation for MediaCodec.createInputSurface.
192 */
193media_status_t AMediaCodec_createInputSurface(
194        AMediaCodec *mData, ANativeWindow **surface);
195
196/**
197 * Creates a persistent Surface that can be used as the input to encoder
198 *
199 * Persistent surface can be reused by MediaCodec instances and can be set
200 * on a new instance via AMediaCodec_setInputSurface().
201 * A persistent surface can be connected to at most one instance of MediaCodec
202 * at any point in time.
203 *
204 * The application is responsible for releasing the surface by calling
205 * ANativeWindow_release() when done.
206 *
207 * For more details, see the Java documentation for MediaCodec.createPersistentInputSurface.
208 */
209media_status_t AMediaCodec_createPersistentInputSurface(
210        ANativeWindow **surface);
211
212/**
213 * Set a persistent-surface that can be used as the input to encoder, in place of input buffers
214 *
215 * The surface provided *must* be a persistent surface created via
216 * AMediaCodec_createPersistentInputSurface()
217 * This can only be called after the codec has been configured by calling
218 * AMediaCodec_configure(..); and before AMediaCodec_start() has been called.
219 *
220 * For more details, see the Java documentation for MediaCodec.setInputSurface.
221 */
222media_status_t AMediaCodec_setInputSurface(
223        AMediaCodec *mData, ANativeWindow *surface);
224
225/**
226 * Signal additional parameters to the codec instance.
227 *
228 * Parameters can be communicated only when the codec is running, i.e
229 * after AMediaCodec_start() has been called.
230 *
231 * NOTE: Some of these parameter changes may silently fail to apply.
232 */
233media_status_t AMediaCodec_setParameters(
234        AMediaCodec *mData, const AMediaFormat* params);
235
236/**
237 * Signals end-of-stream on input. Equivalent to submitting an empty buffer with
238 * AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM set.
239 *
240 * Returns AMEDIA_ERROR_INVALID_OPERATION when used with an encoder not in executing state
241 * or not receiving input from a Surface created by AMediaCodec_createInputSurface or
242 * AMediaCodec_createPersistentInputSurface.
243 *
244 * Returns the previous codec error if one exists.
245 *
246 * Returns AMEDIA_OK when completed succesfully.
247 *
248 * For more details, see the Java documentation for MediaCodec.signalEndOfInputStream.
249 */
250media_status_t AMediaCodec_signalEndOfInputStream(AMediaCodec *mData);
251
252
253
254typedef enum {
255    AMEDIACODECRYPTOINFO_MODE_CLEAR = 0,
256    AMEDIACODECRYPTOINFO_MODE_AES_CTR = 1,
257    AMEDIACODECRYPTOINFO_MODE_AES_WV = 2,
258    AMEDIACODECRYPTOINFO_MODE_AES_CBC = 3
259} cryptoinfo_mode_t;
260
261typedef struct {
262    int32_t encryptBlocks;
263    int32_t skipBlocks;
264} cryptoinfo_pattern_t;
265
266/**
267 * Create an AMediaCodecCryptoInfo from scratch. Use this if you need to use custom
268 * crypto info, rather than one obtained from AMediaExtractor.
269 *
270 * AMediaCodecCryptoInfo describes the structure of an (at least
271 * partially) encrypted input sample.
272 * A buffer's data is considered to be partitioned into "subsamples",
273 * each subsample starts with a (potentially empty) run of plain,
274 * unencrypted bytes followed by a (also potentially empty) run of
275 * encrypted bytes.
276 * numBytesOfClearData can be null to indicate that all data is encrypted.
277 * This information encapsulates per-sample metadata as outlined in
278 * ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files".
279 */
280AMediaCodecCryptoInfo *AMediaCodecCryptoInfo_new(
281        int numsubsamples,
282        uint8_t key[16],
283        uint8_t iv[16],
284        cryptoinfo_mode_t mode,
285        size_t *clearbytes,
286        size_t *encryptedbytes);
287
288/**
289 * delete an AMediaCodecCryptoInfo created previously with AMediaCodecCryptoInfo_new, or
290 * obtained from AMediaExtractor
291 */
292media_status_t AMediaCodecCryptoInfo_delete(AMediaCodecCryptoInfo*);
293
294/**
295 * Set the crypto pattern on an AMediaCryptoInfo object
296 */
297void AMediaCodecCryptoInfo_setPattern(
298        AMediaCodecCryptoInfo *info,
299        cryptoinfo_pattern_t *pattern);
300
301/**
302 * The number of subsamples that make up the buffer's contents.
303 */
304size_t AMediaCodecCryptoInfo_getNumSubSamples(AMediaCodecCryptoInfo*);
305
306/**
307 * A 16-byte opaque key
308 */
309media_status_t AMediaCodecCryptoInfo_getKey(AMediaCodecCryptoInfo*, uint8_t *dst);
310
311/**
312 * A 16-byte initialization vector
313 */
314media_status_t AMediaCodecCryptoInfo_getIV(AMediaCodecCryptoInfo*, uint8_t *dst);
315
316/**
317 * The type of encryption that has been applied,
318 * one of AMEDIACODECRYPTOINFO_MODE_CLEAR or AMEDIACODECRYPTOINFO_MODE_AES_CTR.
319 */
320cryptoinfo_mode_t AMediaCodecCryptoInfo_getMode(AMediaCodecCryptoInfo*);
321
322/**
323 * The number of leading unencrypted bytes in each subsample.
324 */
325media_status_t AMediaCodecCryptoInfo_getClearBytes(AMediaCodecCryptoInfo*, size_t *dst);
326
327/**
328 * The number of trailing encrypted bytes in each subsample.
329 */
330media_status_t AMediaCodecCryptoInfo_getEncryptedBytes(AMediaCodecCryptoInfo*, size_t *dst);
331
332#endif /* __ANDROID_API__ >= 21 */
333
334#ifdef __cplusplus
335} // extern "C"
336#endif
337
338#endif //_NDK_MEDIA_CODEC_H
339