NdkMediaCodec.h revision 18cb1eca504817b5b144a023ae2792d90e74c9a5
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 <android/native_window.h>
31
32#include "NdkMediaCrypto.h"
33#include "NdkMediaError.h"
34#include "NdkMediaFormat.h"
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40
41struct AMediaCodec;
42typedef struct AMediaCodec AMediaCodec;
43
44struct AMediaCodecBufferInfo {
45    int32_t offset;
46    int32_t size;
47    int64_t presentationTimeUs;
48    uint32_t flags;
49};
50typedef struct AMediaCodecBufferInfo AMediaCodecBufferInfo;
51typedef struct AMediaCodecCryptoInfo AMediaCodecCryptoInfo;
52
53enum {
54    AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM = 4,
55    AMEDIACODEC_CONFIGURE_FLAG_ENCODE = 1,
56    AMEDIACODEC_INFO_OUTPUT_BUFFERS_CHANGED = -3,
57    AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED = -2,
58    AMEDIACODEC_INFO_TRY_AGAIN_LATER = -1
59};
60
61/**
62 * Create codec by name. Use this if you know the exact codec you want to use.
63 * When configuring, you will need to specify whether to use the codec as an
64 * encoder or decoder.
65 */
66AMediaCodec* AMediaCodec_createCodecByName(const char *name);
67
68/**
69 * Create codec by mime type. Most applications will use this, specifying a
70 * mime type obtained from media extractor.
71 */
72AMediaCodec* AMediaCodec_createDecoderByType(const char *mime_type);
73
74/**
75 * Create encoder by name.
76 */
77AMediaCodec* AMediaCodec_createEncoderByType(const char *mime_type);
78
79/**
80 * delete the codec and free its resources
81 */
82media_status_t AMediaCodec_delete(AMediaCodec*);
83
84/**
85 * Configure the codec. For decoding you would typically get the format from an extractor.
86 */
87media_status_t AMediaCodec_configure(
88        AMediaCodec*,
89        const AMediaFormat* format,
90        ANativeWindow* surface,
91        AMediaCrypto *crypto,
92        uint32_t flags);
93
94/**
95 * Start the codec. A codec must be configured before it can be started, and must be started
96 * before buffers can be sent to it.
97 */
98media_status_t AMediaCodec_start(AMediaCodec*);
99
100/**
101 * Stop the codec.
102 */
103media_status_t AMediaCodec_stop(AMediaCodec*);
104
105/*
106 * Flush the codec's input and output. All indices previously returned from calls to
107 * AMediaCodec_dequeueInputBuffer and AMediaCodec_dequeueOutputBuffer become invalid.
108 */
109media_status_t AMediaCodec_flush(AMediaCodec*);
110
111/**
112 * Get an input buffer. The specified buffer index must have been previously obtained from
113 * dequeueInputBuffer, and not yet queued.
114 */
115uint8_t* AMediaCodec_getInputBuffer(AMediaCodec*, size_t idx, size_t *out_size);
116
117/**
118 * Get an output buffer. The specified buffer index must have been previously obtained from
119 * dequeueOutputBuffer, and not yet queued.
120 */
121uint8_t* AMediaCodec_getOutputBuffer(AMediaCodec*, size_t idx, size_t *out_size);
122
123/**
124 * Get the index of the next available input buffer. An app will typically use this with
125 * getInputBuffer() to get a pointer to the buffer, then copy the data to be encoded or decoded
126 * into the buffer before passing it to the codec.
127 */
128ssize_t AMediaCodec_dequeueInputBuffer(AMediaCodec*, int64_t timeoutUs);
129
130/**
131 * Send the specified buffer to the codec for processing.
132 */
133media_status_t AMediaCodec_queueInputBuffer(AMediaCodec*,
134        size_t idx, off_t offset, size_t size, uint64_t time, uint32_t flags);
135
136/**
137 * Send the specified buffer to the codec for processing.
138 */
139media_status_t AMediaCodec_queueSecureInputBuffer(AMediaCodec*,
140        size_t idx, off_t offset, AMediaCodecCryptoInfo*, uint64_t time, uint32_t flags);
141
142/**
143 * Get the index of the next available buffer of processed data.
144 */
145ssize_t AMediaCodec_dequeueOutputBuffer(AMediaCodec*, AMediaCodecBufferInfo *info,
146        int64_t timeoutUs);
147AMediaFormat* AMediaCodec_getOutputFormat(AMediaCodec*);
148
149/**
150 * If you are done with a buffer, use this call to return the buffer to
151 * the codec. If you previously specified a surface when configuring this
152 * video decoder you can optionally render the buffer.
153 */
154media_status_t AMediaCodec_releaseOutputBuffer(AMediaCodec*, size_t idx, bool render);
155
156/**
157 * If you are done with a buffer, use this call to update its surface timestamp
158 * and return it to the codec to render it on the output surface. If you
159 * have not specified an output surface when configuring this video codec,
160 * this call will simply return the buffer to the codec.
161 *
162 * For more details, see the Java documentation for MediaCodec.releaseOutputBuffer.
163 */
164media_status_t AMediaCodec_releaseOutputBufferAtTime(
165        AMediaCodec *mData, size_t idx, int64_t timestampNs);
166
167
168typedef enum {
169    AMEDIACODECRYPTOINFO_MODE_CLEAR = 0,
170    AMEDIACODECRYPTOINFO_MODE_AES_CTR = 1
171} cryptoinfo_mode_t;
172
173typedef struct {
174    int32_t encryptBlocks;
175    int32_t skipBlocks;
176} cryptoinfo_pattern_t;
177
178/**
179 * Create an AMediaCodecCryptoInfo from scratch. Use this if you need to use custom
180 * crypto info, rather than one obtained from AMediaExtractor.
181 *
182 * AMediaCodecCryptoInfo describes the structure of an (at least
183 * partially) encrypted input sample.
184 * A buffer's data is considered to be partitioned into "subsamples",
185 * each subsample starts with a (potentially empty) run of plain,
186 * unencrypted bytes followed by a (also potentially empty) run of
187 * encrypted bytes.
188 * numBytesOfClearData can be null to indicate that all data is encrypted.
189 * This information encapsulates per-sample metadata as outlined in
190 * ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files".
191 */
192AMediaCodecCryptoInfo *AMediaCodecCryptoInfo_new(
193        int numsubsamples,
194        uint8_t key[16],
195        uint8_t iv[16],
196        cryptoinfo_mode_t mode,
197        size_t *clearbytes,
198        size_t *encryptedbytes);
199
200/**
201 * delete an AMediaCodecCryptoInfo created previously with AMediaCodecCryptoInfo_new, or
202 * obtained from AMediaExtractor
203 */
204media_status_t AMediaCodecCryptoInfo_delete(AMediaCodecCryptoInfo*);
205
206/**
207 * Set the crypto pattern on an AMediaCryptoInfo object
208 */
209void AMediaCodecCryptoInfo_setPattern(
210        AMediaCodecCryptoInfo *info,
211        cryptoinfo_pattern_t *pattern);
212
213/**
214 * The number of subsamples that make up the buffer's contents.
215 */
216size_t AMediaCodecCryptoInfo_getNumSubSamples(AMediaCodecCryptoInfo*);
217
218/**
219 * A 16-byte opaque key
220 */
221media_status_t AMediaCodecCryptoInfo_getKey(AMediaCodecCryptoInfo*, uint8_t *dst);
222
223/**
224 * A 16-byte initialization vector
225 */
226media_status_t AMediaCodecCryptoInfo_getIV(AMediaCodecCryptoInfo*, uint8_t *dst);
227
228/**
229 * The type of encryption that has been applied,
230 * one of AMEDIACODECRYPTOINFO_MODE_CLEAR or AMEDIACODECRYPTOINFO_MODE_AES_CTR.
231 */
232cryptoinfo_mode_t AMediaCodecCryptoInfo_getMode(AMediaCodecCryptoInfo*);
233
234/**
235 * The number of leading unencrypted bytes in each subsample.
236 */
237media_status_t AMediaCodecCryptoInfo_getClearBytes(AMediaCodecCryptoInfo*, size_t *dst);
238
239/**
240 * The number of trailing encrypted bytes in each subsample.
241 */
242media_status_t AMediaCodecCryptoInfo_getEncryptedBytes(AMediaCodecCryptoInfo*, size_t *dst);
243
244#ifdef __cplusplus
245} // extern "C"
246#endif
247
248#endif //_NDK_MEDIA_CODEC_H
249