1 /* 2 * Copyright (C) 2009 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 * @addtogroup Bitmap 19 * @{ 20 */ 21 22 /** 23 * @file bitmap.h 24 */ 25 26 #ifndef ANDROID_BITMAP_H 27 #define ANDROID_BITMAP_H 28 29 #include <stdbool.h> 30 #include <stdint.h> 31 #include <stddef.h> 32 #include <jni.h> 33 34 #if !defined(__INTRODUCED_IN) 35 #define __INTRODUCED_IN(__api_level) /* nothing */ 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** AndroidBitmap functions result code. */ 43 enum { 44 /** Operation was successful. */ 45 ANDROID_BITMAP_RESULT_SUCCESS = 0, 46 /** Bad parameter. */ 47 ANDROID_BITMAP_RESULT_BAD_PARAMETER = -1, 48 /** JNI exception occured. */ 49 ANDROID_BITMAP_RESULT_JNI_EXCEPTION = -2, 50 /** Allocation failed. */ 51 ANDROID_BITMAP_RESULT_ALLOCATION_FAILED = -3, 52 }; 53 54 /** Backward compatibility: this macro used to be misspelled. */ 55 #define ANDROID_BITMAP_RESUT_SUCCESS ANDROID_BITMAP_RESULT_SUCCESS 56 57 /** Bitmap pixel format. */ 58 enum AndroidBitmapFormat { 59 /** No format. */ 60 ANDROID_BITMAP_FORMAT_NONE = 0, 61 /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/ 62 ANDROID_BITMAP_FORMAT_RGBA_8888 = 1, 63 /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/ 64 ANDROID_BITMAP_FORMAT_RGB_565 = 4, 65 /** Deprecated in API level 13. Because of the poor quality of this configuration, it is advised to use ARGB_8888 instead. **/ 66 ANDROID_BITMAP_FORMAT_RGBA_4444 = 7, 67 /** Alpha: 8 bits. */ 68 ANDROID_BITMAP_FORMAT_A_8 = 8, 69 /** Each component is stored as a half float. **/ 70 ANDROID_BITMAP_FORMAT_RGBA_F16 = 9, 71 /** Red: 10 bits, Green: 10 bits, Blue: 10 bits, Alpha: 2 bits. **/ 72 ANDROID_BITMAP_FORMAT_RGBA_1010102 = 10, 73 }; 74 75 /** Bitmap alpha format */ 76 enum { 77 /** Pixel components are premultiplied by alpha. */ 78 ANDROID_BITMAP_FLAGS_ALPHA_PREMUL = 0, 79 /** Pixels are opaque. */ 80 ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE = 1, 81 /** Pixel components are independent of alpha. */ 82 ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL = 2, 83 /** Bit mask for AndroidBitmapFormat.flags to isolate the alpha. */ 84 ANDROID_BITMAP_FLAGS_ALPHA_MASK = 0x3, 85 /** Shift for AndroidBitmapFormat.flags to isolate the alpha. */ 86 ANDROID_BITMAP_FLAGS_ALPHA_SHIFT = 0, 87 }; 88 89 enum { 90 /** If this bit is set in AndroidBitmapInfo.flags, the Bitmap uses the 91 * HARDWARE Config, and its {@link AHardwareBuffer} can be retrieved via 92 * {@link AndroidBitmap_getHardwareBuffer}. 93 */ 94 ANDROID_BITMAP_FLAGS_IS_HARDWARE = 1 << 31, 95 }; 96 97 /** Bitmap info, see AndroidBitmap_getInfo(). */ 98 typedef struct { 99 /** The bitmap width in pixels. */ 100 uint32_t width; 101 /** The bitmap height in pixels. */ 102 uint32_t height; 103 /** The number of byte per row. */ 104 uint32_t stride; 105 /** The bitmap pixel format. See {@link AndroidBitmapFormat} */ 106 int32_t format; 107 /** Bitfield containing information about the bitmap. 108 * 109 * <p>Two bits are used to encode alpha. Use {@link ANDROID_BITMAP_FLAGS_ALPHA_MASK} 110 * and {@link ANDROID_BITMAP_FLAGS_ALPHA_SHIFT} to retrieve them.</p> 111 * 112 * <p>One bit is used to encode whether the Bitmap uses the HARDWARE Config. Use 113 * {@link ANDROID_BITMAP_FLAGS_IS_HARDWARE} to know.</p> 114 * 115 * <p>These flags were introduced in API level 30.</p> 116 */ 117 uint32_t flags; 118 } AndroidBitmapInfo; 119 120 /** 121 * Given a java bitmap object, fill out the {@link AndroidBitmapInfo} struct for it. 122 * If the call fails, the info parameter will be ignored. 123 */ 124 int AndroidBitmap_getInfo(JNIEnv* env, jobject jbitmap, 125 AndroidBitmapInfo* info); 126 127 /** 128 * Given a java bitmap object, return its {@link ADataSpace}. 129 * 130 * Note that {@link ADataSpace} only exposes a few values. This may return 131 * {@link ADATASPACE_UNKNOWN}, even for Named ColorSpaces, if they have no 132 * corresponding ADataSpace. 133 * 134 * Available since API level 30. 135 */ 136 int32_t AndroidBitmap_getDataSpace(JNIEnv* env, jobject jbitmap) __INTRODUCED_IN(30); 137 138 /** 139 * Given a java bitmap object, attempt to lock the pixel address. 140 * Locking will ensure that the memory for the pixels will not move 141 * until the unlockPixels call, and ensure that, if the pixels had been 142 * previously purged, they will have been restored. 143 * 144 * If this call succeeds, it must be balanced by a call to 145 * AndroidBitmap_unlockPixels, after which time the address of the pixels should 146 * no longer be used. 147 * 148 * If this succeeds, *addrPtr will be set to the pixel address. If the call 149 * fails, addrPtr will be ignored. 150 */ 151 int AndroidBitmap_lockPixels(JNIEnv* env, jobject jbitmap, void** addrPtr); 152 153 /** 154 * Call this to balance a successful call to AndroidBitmap_lockPixels. 155 */ 156 int AndroidBitmap_unlockPixels(JNIEnv* env, jobject jbitmap); 157 158 // Note: these values match android.graphics.Bitmap#compressFormat. 159 160 /** 161 * Specifies the formats that can be compressed to with 162 * {@link AndroidBitmap_compress}. 163 */ 164 enum AndroidBitmapCompressFormat { 165 /** 166 * Compress to the JPEG format. quality of 0 means 167 * compress for the smallest size. 100 means compress for max 168 * visual quality. 169 */ 170 ANDROID_BITMAP_COMPRESS_FORMAT_JPEG = 0, 171 /** 172 * Compress to the PNG format. PNG is lossless, so quality is 173 * ignored. 174 */ 175 ANDROID_BITMAP_COMPRESS_FORMAT_PNG = 1, 176 /** 177 * Compress to the WEBP lossy format. quality of 0 means 178 * compress for the smallest size. 100 means compress for max 179 * visual quality. 180 */ 181 ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSY = 3, 182 /** 183 * Compress to the WEBP lossless format. quality refers to how 184 * much effort to put into compression. A value of 0 means to 185 * compress quickly, resulting in a relatively large file size. 186 * 100 means to spend more time compressing, resulting in a 187 * smaller file. 188 */ 189 ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSLESS = 4, 190 }; 191 192 /** 193 * User-defined function for writing the output of compression. 194 * 195 * Available since API level 30. 196 * 197 * @param userContext Pointer to user-defined data passed to 198 * {@link AndroidBitmap_compress}. 199 * @param data Compressed data of |size| bytes to write. 200 * @param size Length in bytes of data to write. 201 * @return Whether the operation succeeded. 202 */ 203 typedef bool (*AndroidBitmap_CompressWriteFunc)(void* userContext, 204 const void* data, 205 size_t size) __INTRODUCED_IN(30); 206 207 /** 208 * Compress |pixels| as described by |info|. 209 * 210 * Available since API level 30. 211 * 212 * @param info Description of the pixels to compress. 213 * @param dataspace {@link ADataSpace} describing the color space of the 214 * pixels. 215 * @param pixels Pointer to pixels to compress. 216 * @param format {@link AndroidBitmapCompressFormat} to compress to. 217 * @param quality Hint to the compressor, 0-100. The value is interpreted 218 * differently depending on the 219 * {@link AndroidBitmapCompressFormat}. 220 * @param userContext User-defined data which will be passed to the supplied 221 * {@link AndroidBitmap_CompressWriteFunc} each time it is 222 * called. May be null. 223 * @param fn Function that writes the compressed data. Will be called each time 224 * the compressor has compressed more data that is ready to be 225 * written. May be called more than once for each call to this method. 226 * May not be null. 227 * @return AndroidBitmap functions result code. 228 */ 229 int AndroidBitmap_compress(const AndroidBitmapInfo* info, 230 int32_t dataspace, 231 const void* pixels, 232 int32_t format, int32_t quality, 233 void* userContext, 234 AndroidBitmap_CompressWriteFunc fn) __INTRODUCED_IN(30); 235 236 struct AHardwareBuffer; 237 typedef struct AHardwareBuffer AHardwareBuffer; 238 239 /** 240 * Retrieve the native object associated with a HARDWARE Bitmap. 241 * 242 * Client must not modify it while a Bitmap is wrapping it. 243 * 244 * Available since API level 30. 245 * 246 * @param env Handle to the JNI environment pointer. 247 * @param bitmap Handle to an android.graphics.Bitmap. 248 * @param outBuffer On success, is set to a pointer to the 249 * {@link AHardwareBuffer} associated with bitmap. This acquires 250 * a reference on the buffer, and the client must call 251 * {@link AHardwareBuffer_release} when finished with it. 252 * @return AndroidBitmap functions result code. 253 * {@link ANDROID_BITMAP_RESULT_BAD_PARAMETER} if bitmap is not a 254 * HARDWARE Bitmap. 255 */ 256 int AndroidBitmap_getHardwareBuffer(JNIEnv* env, jobject bitmap, 257 AHardwareBuffer** outBuffer) __INTRODUCED_IN(30); 258 259 #ifdef __cplusplus 260 } 261 #endif 262 263 #endif 264 265 /** @} */ 266