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 37 extern "C" { 38 #endif 39 40 41 struct AMediaCodec; 42 typedef struct AMediaCodec AMediaCodec; 43 44 struct AMediaCodecBufferInfo { 45 int32_t offset; 46 int32_t size; 47 int64_t presentationTimeUs; 48 uint32_t flags; 49 }; 50 typedef struct AMediaCodecBufferInfo AMediaCodecBufferInfo; 51 typedef struct AMediaCodecCryptoInfo AMediaCodecCryptoInfo; 52 53 enum { 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 */ 66 AMediaCodec* 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 */ 72 AMediaCodec* AMediaCodec_createDecoderByType(const char *mime_type); 73 74 /** 75 * Create encoder by name. 76 */ 77 AMediaCodec* AMediaCodec_createEncoderByType(const char *mime_type); 78 79 /** 80 * delete the codec and free its resources 81 */ 82 media_status_t AMediaCodec_delete(AMediaCodec*); 83 84 /** 85 * Configure the codec. For decoding you would typically get the format from an extractor. 86 */ 87 media_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 */ 98 media_status_t AMediaCodec_start(AMediaCodec*); 99 100 /** 101 * Stop the codec. 102 */ 103 media_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 */ 109 media_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 */ 115 uint8_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 */ 121 uint8_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 */ 128 ssize_t AMediaCodec_dequeueInputBuffer(AMediaCodec*, int64_t timeoutUs); 129 130 /** 131 * Send the specified buffer to the codec for processing. 132 */ 133 media_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 */ 139 media_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 */ 145 ssize_t AMediaCodec_dequeueOutputBuffer(AMediaCodec*, AMediaCodecBufferInfo *info, 146 int64_t timeoutUs); 147 AMediaFormat* 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 */ 154 media_status_t AMediaCodec_releaseOutputBuffer(AMediaCodec*, size_t idx, bool render); 155 156 /** 157 * Dynamically sets the output surface of a codec. 158 * 159 * This can only be used if the codec was configured with an output surface. The 160 * new output surface should have a compatible usage type to the original output surface. 161 * E.g. codecs may not support switching from a SurfaceTexture (GPU readable) output 162 * to ImageReader (software readable) output. 163 * 164 * For more details, see the Java documentation for MediaCodec.setOutputSurface. 165 */ 166 media_status_t AMediaCodec_setOutputSurface(AMediaCodec*, ANativeWindow* surface); 167 168 /** 169 * If you are done with a buffer, use this call to update its surface timestamp 170 * and return it to the codec to render it on the output surface. If you 171 * have not specified an output surface when configuring this video codec, 172 * this call will simply return the buffer to the codec. 173 * 174 * For more details, see the Java documentation for MediaCodec.releaseOutputBuffer. 175 */ 176 media_status_t AMediaCodec_releaseOutputBufferAtTime( 177 AMediaCodec *mData, size_t idx, int64_t timestampNs); 178 179 typedef enum { 180 AMEDIACODECRYPTOINFO_MODE_CLEAR = 0, 181 AMEDIACODECRYPTOINFO_MODE_AES_CTR = 1, 182 AMEDIACODECRYPTOINFO_MODE_AES_WV = 2, 183 AMEDIACODECRYPTOINFO_MODE_AES_CBC = 3 184 } cryptoinfo_mode_t; 185 186 typedef struct { 187 int32_t encryptBlocks; 188 int32_t skipBlocks; 189 } cryptoinfo_pattern_t; 190 191 /** 192 * Create an AMediaCodecCryptoInfo from scratch. Use this if you need to use custom 193 * crypto info, rather than one obtained from AMediaExtractor. 194 * 195 * AMediaCodecCryptoInfo describes the structure of an (at least 196 * partially) encrypted input sample. 197 * A buffer's data is considered to be partitioned into "subsamples", 198 * each subsample starts with a (potentially empty) run of plain, 199 * unencrypted bytes followed by a (also potentially empty) run of 200 * encrypted bytes. 201 * numBytesOfClearData can be null to indicate that all data is encrypted. 202 * This information encapsulates per-sample metadata as outlined in 203 * ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files". 204 */ 205 AMediaCodecCryptoInfo *AMediaCodecCryptoInfo_new( 206 int numsubsamples, 207 uint8_t key[16], 208 uint8_t iv[16], 209 cryptoinfo_mode_t mode, 210 size_t *clearbytes, 211 size_t *encryptedbytes); 212 213 /** 214 * delete an AMediaCodecCryptoInfo created previously with AMediaCodecCryptoInfo_new, or 215 * obtained from AMediaExtractor 216 */ 217 media_status_t AMediaCodecCryptoInfo_delete(AMediaCodecCryptoInfo*); 218 219 /** 220 * Set the crypto pattern on an AMediaCryptoInfo object 221 */ 222 void AMediaCodecCryptoInfo_setPattern( 223 AMediaCodecCryptoInfo *info, 224 cryptoinfo_pattern_t *pattern); 225 226 /** 227 * The number of subsamples that make up the buffer's contents. 228 */ 229 size_t AMediaCodecCryptoInfo_getNumSubSamples(AMediaCodecCryptoInfo*); 230 231 /** 232 * A 16-byte opaque key 233 */ 234 media_status_t AMediaCodecCryptoInfo_getKey(AMediaCodecCryptoInfo*, uint8_t *dst); 235 236 /** 237 * A 16-byte initialization vector 238 */ 239 media_status_t AMediaCodecCryptoInfo_getIV(AMediaCodecCryptoInfo*, uint8_t *dst); 240 241 /** 242 * The type of encryption that has been applied, 243 * one of AMEDIACODECRYPTOINFO_MODE_CLEAR or AMEDIACODECRYPTOINFO_MODE_AES_CTR. 244 */ 245 cryptoinfo_mode_t AMediaCodecCryptoInfo_getMode(AMediaCodecCryptoInfo*); 246 247 /** 248 * The number of leading unencrypted bytes in each subsample. 249 */ 250 media_status_t AMediaCodecCryptoInfo_getClearBytes(AMediaCodecCryptoInfo*, size_t *dst); 251 252 /** 253 * The number of trailing encrypted bytes in each subsample. 254 */ 255 media_status_t AMediaCodecCryptoInfo_getEncryptedBytes(AMediaCodecCryptoInfo*, size_t *dst); 256 257 #ifdef __cplusplus 258 } // extern "C" 259 #endif 260 261 #endif //_NDK_MEDIA_CODEC_H 262