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