include/android/bitmap.h

/*
 * Copyright (C) 2009 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup Bitmap
 * @{
 */

/**
 * @file bitmap.h
 */

#ifndef ANDROID_BITMAP_H
#define ANDROID_BITMAP_H

#include <stdbool.h>
#include <stdint.h>
#include <jni.h>

#ifdef __cplusplus
extern "C" {
#endif

/** AndroidBitmap functions result code. */
enum {
    /** Operation was successful. */
    ANDROID_BITMAP_RESULT_SUCCESS           = 0,
    /** Bad parameter. */
    ANDROID_BITMAP_RESULT_BAD_PARAMETER     = -1,
    /** JNI exception occured. */
    ANDROID_BITMAP_RESULT_JNI_EXCEPTION     = -2,
    /** Allocation failed. */
    ANDROID_BITMAP_RESULT_ALLOCATION_FAILED = -3,
};

/** Backward compatibility: this macro used to be misspelled. */
#define ANDROID_BITMAP_RESUT_SUCCESS ANDROID_BITMAP_RESULT_SUCCESS

/** Bitmap pixel format. */
enum AndroidBitmapFormat {
    /** No format. */
    ANDROID_BITMAP_FORMAT_NONE      = 0,
    /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
    ANDROID_BITMAP_FORMAT_RGBA_8888 = 1,
    /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
    ANDROID_BITMAP_FORMAT_RGB_565   = 4,
    /** Deprecated in API level 13. Because of the poor quality of this configuration, it is advised to use ARGB_8888 instead. **/
    ANDROID_BITMAP_FORMAT_RGBA_4444 = 7,
    /** Alpha: 8 bits. */
    ANDROID_BITMAP_FORMAT_A_8       = 8,
    /** Each component is stored as a half float. **/
    ANDROID_BITMAP_FORMAT_RGBA_F16  = 9,
};

/** Bitmap alpha format */
enum {
    /** Pixel components are premultiplied by alpha. */
    ANDROID_BITMAP_FLAGS_ALPHA_PREMUL   = 0,
    /** Pixels are opaque. */
    ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE   = 1,
    /** Pixel components are independent of alpha. */
    ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL = 2,
    /** Bit mask for AndroidBitmapFormat.flags to isolate the alpha. */
    ANDROID_BITMAP_FLAGS_ALPHA_MASK     = 0x3,
    /** Shift for AndroidBitmapFormat.flags to isolate the alpha. */
    ANDROID_BITMAP_FLAGS_ALPHA_SHIFT    = 0,
};

enum {
    /** If this bit is set in AndroidBitmapInfo.flags, the Bitmap uses the
      * HARDWARE Config, and its AHardwareBuffer can be retrieved via
      * AndroidBitmap_getHardwareBuffer.
      */
    ANDROID_BITMAP_FLAGS_IS_HARDWARE = 1 << 31,
};

/** Bitmap info, see AndroidBitmap_getInfo(). */
typedef struct {
    /** The bitmap width in pixels. */
    uint32_t    width;
    /** The bitmap height in pixels. */
    uint32_t    height;
    /** The number of byte per row. */
    uint32_t    stride;
    /** The bitmap pixel format. See {@link AndroidBitmapFormat} */
    int32_t     format;
    /** Bitfield containing information about the bitmap.
     *
     * <p>Two bits are used to encode alpha. Use {@link ANDROID_BITMAP_FLAGS_ALPHA_MASK}
     * and {@link ANDROID_BITMAP_FLAGS_ALPHA_SHIFT} to retrieve them.</p>
     *
     * <p>One bit is used to encode whether the Bitmap uses the HARDWARE Config. Use
     * {@link ANDROID_BITMAP_FLAGS_IS_HARDWARE} to know.</p>
     *
     * <p>These flags were introduced in API level 30.</p>
     */
    uint32_t    flags;
} AndroidBitmapInfo;

/**
 * Given a java bitmap object, fill out the {@link AndroidBitmapInfo} struct for it.
 * If the call fails, the info parameter will be ignored.
 */
int AndroidBitmap_getInfo(JNIEnv* env, jobject jbitmap,
                          AndroidBitmapInfo* info);

#if __ANDROID_API__ >= 30

/**
 * Given a java bitmap object, return its ADataSpace.
 *
 * Note that ADataSpace only exposes a few values. This may return
 * ADATASPACE_UNKNOWN, even for Named ColorSpaces, if they have no
 * corresponding ADataSpace.
 */
int32_t AndroidBitmap_getDataSpace(JNIEnv* env, jobject jbitmap)  __INTRODUCED_IN(30);

#endif // __ANDROID_API__ >= 30

/**
 * Given a java bitmap object, attempt to lock the pixel address.
 * Locking will ensure that the memory for the pixels will not move
 * until the unlockPixels call, and ensure that, if the pixels had been
 * previously purged, they will have been restored.
 *
 * If this call succeeds, it must be balanced by a call to
 * AndroidBitmap_unlockPixels, after which time the address of the pixels should
 * no longer be used.
 *
 * If this succeeds, *addrPtr will be set to the pixel address. If the call
 * fails, addrPtr will be ignored.
 */
int AndroidBitmap_lockPixels(JNIEnv* env, jobject jbitmap, void** addrPtr);

/**
 * Call this to balance a successful call to AndroidBitmap_lockPixels.
 */
int AndroidBitmap_unlockPixels(JNIEnv* env, jobject jbitmap);

#if __ANDROID_API__ >= 30

// Note: these values match android.graphics.Bitmap#compressFormat.

/**
 *  Specifies the formats that can be compressed to with
 *  {@link AndroidBitmap_compress}.
 */
enum AndroidBitmapCompressFormat {
    /**
     * Compress to the JPEG format. quality of 0 means
     * compress for the smallest size. 100 means compress for max
     * visual quality.
     */
    ANDROID_BITMAP_COMPRESS_FORMAT_JPEG = 0,
    /**
     * Compress to the PNG format. PNG is lossless, so quality is
     * ignored.
     */
    ANDROID_BITMAP_COMPRESS_FORMAT_PNG = 1,
    /**
     * Compress to the WEBP lossy format. quality of 0 means
     * compress for the smallest size. 100 means compress for max
     * visual quality.
     */
    ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSY = 3,
    /**
     * Compress to the WEBP lossless format. quality refers to how
     * much effort to put into compression. A value of 0 means to
     * compress quickly, resulting in a relatively large file size.
     * 100 means to spend more time compressing, resulting in a
     * smaller file.
     */
    ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSLESS = 4,
};

/**
 *  User-defined function for writing the output of compression.
 *
 *  @param userContext Pointer to user-defined data passed to
 *         {@link AndroidBitmap_compress}.
 *  @param data Compressed data of |size| bytes to write.
 *  @param size Length in bytes of data to write.
 *  @return Whether the operation succeeded.
 */
typedef bool (*AndroidBitmap_CompressWriteFunc)(void* userContext,
                                                const void* data,
                                                size_t size) __INTRODUCED_IN(30);

/**
 *  Compress |pixels| as described by |info|.
 *
 *  @param info Description of the pixels to compress.
 *  @param dataspace {@link ADataSpace} describing the color space of the
 *                   pixels.
 *  @param pixels Pointer to pixels to compress.
 *  @param format (@link AndroidBitmapCompressFormat} to compress to.
 *  @param quality Hint to the compressor, 0-100. The value is interpreted
 *                 differently depending on the
 *                 {@link AndroidBitmapCompressFormat}.
 *  @param userContext User-defined data which will be passed to the supplied
 *                     {@link AndroidBitmap_CompressWriteFunc} each time it is
 *                     called. May be null.
 *  @parm fn Function that writes the compressed data. Will be called each time
 *           the compressor has compressed more data that is ready to be
 *           written. May be called more than once for each call to this method.
 *           May not be null.
 *  @return AndroidBitmap functions result code.
 */
int AndroidBitmap_compress(const AndroidBitmapInfo* info,
                           int32_t dataspace,
                           const void* pixels,
                           int32_t format, int32_t quality,
                           void* userContext,
                           AndroidBitmap_CompressWriteFunc fn) __INTRODUCED_IN(30);

struct AHardwareBuffer;

/**
 *  Retrieve the native object associated with a HARDWARE Bitmap.
 *
 *  Client must not modify it while a Bitmap is wrapping it.
 *
 *  @param bitmap Handle to an android.graphics.Bitmap.
 *  @param outBuffer On success, is set to a pointer to the
 *         AHardwareBuffer associated with bitmap. This acquires
 *         a reference on the buffer, and the client must call
 *         AHardwareBuffer_release when finished with it.
 *  @return AndroidBitmap functions result code.
 *          ANDROID_BITMAP_RESULT_BAD_PARAMETER if bitmap is not a
 *          HARDWARE Bitmap.
 */
int AndroidBitmap_getHardwareBuffer(JNIEnv* env, jobject bitmap,
        AHardwareBuffer** outBuffer) __INTRODUCED_IN(30);

#endif // __ANDROID_API__ >= 30

#ifdef __cplusplus
}
#endif

#endif

/** @} */