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