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 37 extern "C" { 38 #endif 39 40 struct ANativeWindow; 41 42 #if __ANDROID_API__ >= 21 43 44 struct AMediaCodec; 45 typedef struct AMediaCodec AMediaCodec; 46 47 struct AMediaCodecBufferInfo { 48 int32_t offset; 49 int32_t size; 50 int64_t presentationTimeUs; 51 uint32_t flags; 52 }; 53 typedef struct AMediaCodecBufferInfo AMediaCodecBufferInfo; 54 typedef struct AMediaCodecCryptoInfo AMediaCodecCryptoInfo; 55 56 enum { 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 */ 69 AMediaCodec* 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 */ 75 AMediaCodec* AMediaCodec_createDecoderByType(const char *mime_type); 76 77 /** 78 * Create encoder by name. 79 */ 80 AMediaCodec* AMediaCodec_createEncoderByType(const char *mime_type); 81 82 /** 83 * delete the codec and free its resources 84 */ 85 media_status_t AMediaCodec_delete(AMediaCodec*); 86 87 /** 88 * Configure the codec. For decoding you would typically get the format from an extractor. 89 */ 90 media_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 */ 101 media_status_t AMediaCodec_start(AMediaCodec*); 102 103 /** 104 * Stop the codec. 105 */ 106 media_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 */ 112 media_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 */ 118 uint8_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 */ 124 uint8_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 */ 131 ssize_t AMediaCodec_dequeueInputBuffer(AMediaCodec*, int64_t timeoutUs); 132 133 /** 134 * Send the specified buffer to the codec for processing. 135 */ 136 media_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 */ 142 media_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 */ 148 ssize_t AMediaCodec_dequeueOutputBuffer(AMediaCodec*, AMediaCodecBufferInfo *info, 149 int64_t timeoutUs); 150 AMediaFormat* 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 */ 157 media_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 */ 169 media_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 */ 179 media_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 */ 193 media_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 */ 209 media_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 */ 222 media_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 */ 233 media_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 */ 250 media_status_t AMediaCodec_signalEndOfInputStream(AMediaCodec *mData); 251 252 253 254 typedef 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 261 typedef 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 */ 280 AMediaCodecCryptoInfo *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 */ 292 media_status_t AMediaCodecCryptoInfo_delete(AMediaCodecCryptoInfo*); 293 294 /** 295 * Set the crypto pattern on an AMediaCryptoInfo object 296 */ 297 void 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 */ 304 size_t AMediaCodecCryptoInfo_getNumSubSamples(AMediaCodecCryptoInfo*); 305 306 /** 307 * A 16-byte opaque key 308 */ 309 media_status_t AMediaCodecCryptoInfo_getKey(AMediaCodecCryptoInfo*, uint8_t *dst); 310 311 /** 312 * A 16-byte initialization vector 313 */ 314 media_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 */ 320 cryptoinfo_mode_t AMediaCodecCryptoInfo_getMode(AMediaCodecCryptoInfo*); 321 322 /** 323 * The number of leading unencrypted bytes in each subsample. 324 */ 325 media_status_t AMediaCodecCryptoInfo_getClearBytes(AMediaCodecCryptoInfo*, size_t *dst); 326 327 /** 328 * The number of trailing encrypted bytes in each subsample. 329 */ 330 media_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