Home | History | Annotate | Download | only in ndk
      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