Home | History | Annotate | Download | only in include 
      1 /*
      2  * Copyright (C) 2017 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 #ifndef _HEIF_DECODER_API_
     18 #define _HEIF_DECODER_API_
     19 
     20 #include <memory>
     21 
     22 /*
     23  * The output color pixel format of heif decoder.
     24  */
     25 typedef enum {
     26     kHeifColorFormat_RGB565     = 0,
     27     kHeifColorFormat_RGBA_8888  = 1,
     28     kHeifColorFormat_BGRA_8888  = 2,
     29 } HeifColorFormat;
     30 
     31 /*
     32  * The color spaces encoded in the heif image.
     33  */
     34 typedef enum {
     35     kHeifEncodedColor_RGB = 0,
     36     kHeifEncodedColor_YUV = 1,
     37     kHeifEncodedColor_CMYK = 2,
     38 } HeifEncodedColor;
     39 
     40 /*
     41  * Represents a color converted (RGB-based) video frame
     42  */
     43 struct HeifFrameInfo
     44 {
     45     HeifFrameInfo() :
     46         mWidth(0), mHeight(0), mRotationAngle(0), mBytesPerPixel(0),
     47         mIccSize(0), mIccData(nullptr) {}
     48 
     49     // update the frame info, will make a copy of |iccData| internally
     50     void set(uint32_t width, uint32_t height, int32_t rotation, uint32_t bpp,
     51             uint32_t iccSize, uint8_t* iccData) {
     52         mWidth = width;
     53         mHeight = height;
     54         mRotationAngle = rotation;
     55         mBytesPerPixel = bpp;
     56 
     57         if (mIccData != nullptr) {
     58             mIccData.reset(nullptr);
     59         }
     60         mIccSize = iccSize;
     61         if (iccSize > 0) {
     62             mIccData.reset(new uint8_t[iccSize]);
     63             if (mIccData.get() != nullptr) {
     64                 memcpy(mIccData.get(), iccData, iccSize);
     65             } else {
     66                 mIccSize = 0;
     67             }
     68         }
     69     }
     70 
     71     // Intentional public access modifiers:
     72     uint32_t mWidth;
     73     uint32_t mHeight;
     74     int32_t  mRotationAngle;           // Rotation angle, clockwise, should be multiple of 90
     75     uint32_t mBytesPerPixel;           // Number of bytes for one pixel
     76     uint32_t mIccSize;                 // Number of bytes in mIccData
     77     std::unique_ptr<uint8_t[]> mIccData; // Actual ICC data, memory is owned by this structure
     78 };
     79 
     80 /*
     81  * Abstract interface to provide data to HeifDecoder.
     82  */
     83 struct HeifStream {
     84     HeifStream() {}
     85 
     86     virtual ~HeifStream() {}
     87 
     88     /*
     89      * Reads or skips size number of bytes. return the number of bytes actually
     90      * read or skipped.
     91      * If |buffer| == NULL, skip size bytes, return how many were skipped.
     92      * If |buffer| != NULL, copy size bytes into buffer, return how many were copied.
     93      */
     94     virtual size_t read(void* buffer, size_t size) = 0;
     95 
     96     /*
     97      * Rewinds to the beginning of the stream. Returns true if the stream is known
     98      * to be at the beginning after this call returns.
     99      */
    100     virtual bool rewind() = 0;
    101 
    102     /*
    103      * Seeks to an absolute position in the stream. If this cannot be done, returns false.
    104      * If an attempt is made to seek past the end of the stream, the position will be set
    105      * to the end of the stream.
    106      */
    107     virtual bool seek(size_t /*position*/) = 0;
    108 
    109     /** Returns true if this stream can report its total length. */
    110     virtual bool hasLength() const = 0;
    111 
    112     /** Returns the total length of the stream. If this cannot be done, returns 0. */
    113     virtual size_t getLength() const = 0;
    114 
    115 private:
    116     HeifStream(const HeifFrameInfo&) = delete;
    117     HeifStream& operator=(const HeifFrameInfo&) = delete;
    118 };
    119 
    120 /*
    121  * Abstract interface to decode heif images from a HeifStream data source.
    122  */
    123 struct HeifDecoder {
    124     HeifDecoder() {}
    125 
    126     virtual ~HeifDecoder() {}
    127 
    128     /*
    129      * Returns true if it successfully sets outColor to the encoded color,
    130      * and false otherwise.
    131      */
    132     virtual bool getEncodedColor(HeifEncodedColor* outColor) const = 0;
    133 
    134     /*
    135      * Returns true if it successfully sets the output color format to color,
    136      * and false otherwise.
    137      */
    138     virtual bool setOutputColor(HeifColorFormat color) = 0;
    139 
    140     /*
    141      * Returns true if it successfully initialize heif decoder with source,
    142      * and false otherwise. |frameInfo| will be filled with information of
    143      * the primary picture upon success and unmodified upon failure.
    144      * Takes ownership of |stream| regardless of result.
    145      */
    146     virtual bool init(HeifStream* stream, HeifFrameInfo* frameInfo) = 0;
    147 
    148     /*
    149      * Decode the picture internally, returning whether it succeeded. |frameInfo|
    150      * will be filled with information of the primary picture upon success and
    151      * unmodified upon failure.
    152      *
    153      * After this succeeded, getScanline can be called to read the scanlines
    154      * that were decoded.
    155      */
    156     virtual bool decode(HeifFrameInfo* frameInfo) = 0;
    157 
    158     /*
    159      * Read the next scanline (in top-down order), returns true upon success
    160      * and false otherwise.
    161      */
    162     virtual bool getScanline(uint8_t* dst) = 0;
    163 
    164     /*
    165      * Skip the next |count| scanlines, returns true upon success and
    166      * false otherwise.
    167      */
    168     virtual size_t skipScanlines(size_t count) = 0;
    169 
    170 private:
    171     HeifDecoder(const HeifFrameInfo&) = delete;
    172     HeifDecoder& operator=(const HeifFrameInfo&) = delete;
    173 };
    174 
    175 /*
    176  * Creates a HeifDecoder. Returns a HeifDecoder instance upon success, or NULL
    177  * if the creation has failed.
    178  */
    179 HeifDecoder* createHeifDecoder();
    180 
    181 #endif // _HEIF_DECODER_API_
    182