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