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 <stdint.h>
30#include <jni.h>
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36/** AndroidBitmap functions result code. */
37enum {
38    /** Operation was successful. */
39    ANDROID_BITMAP_RESULT_SUCCESS           = 0,
40    /** Bad parameter. */
41    ANDROID_BITMAP_RESULT_BAD_PARAMETER     = -1,
42    /** JNI exception occured. */
43    ANDROID_BITMAP_RESULT_JNI_EXCEPTION     = -2,
44    /** Allocation failed. */
45    ANDROID_BITMAP_RESULT_ALLOCATION_FAILED = -3,
46};
47
48/** Backward compatibility: this macro used to be misspelled. */
49#define ANDROID_BITMAP_RESUT_SUCCESS ANDROID_BITMAP_RESULT_SUCCESS
50
51/** Bitmap pixel format. */
52enum AndroidBitmapFormat {
53    /** No format. */
54    ANDROID_BITMAP_FORMAT_NONE      = 0,
55    /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
56    ANDROID_BITMAP_FORMAT_RGBA_8888 = 1,
57    /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
58    ANDROID_BITMAP_FORMAT_RGB_565   = 4,
59    /** Deprecated in API level 13. Because of the poor quality of this configuration, it is advised to use ARGB_8888 instead. **/
60    ANDROID_BITMAP_FORMAT_RGBA_4444 = 7,
61    /** Alpha: 8 bits. */
62    ANDROID_BITMAP_FORMAT_A_8       = 8,
63};
64
65/** Bitmap info, see AndroidBitmap_getInfo(). */
66typedef struct {
67    /** The bitmap width in pixels. */
68    uint32_t    width;
69    /** The bitmap height in pixels. */
70    uint32_t    height;
71    /** The number of byte per row. */
72    uint32_t    stride;
73    /** The bitmap pixel format. See {@link AndroidBitmapFormat} */
74    int32_t     format;
75    /** Unused. */
76    uint32_t    flags;      // 0 for now
77} AndroidBitmapInfo;
78
79/**
80 * Given a java bitmap object, fill out the AndroidBitmapInfo struct for it.
81 * If the call fails, the info parameter will be ignored.
82 */
83int AndroidBitmap_getInfo(JNIEnv* env, jobject jbitmap,
84                          AndroidBitmapInfo* info);
85
86/**
87 * Given a java bitmap object, attempt to lock the pixel address.
88 * Locking will ensure that the memory for the pixels will not move
89 * until the unlockPixels call, and ensure that, if the pixels had been
90 * previously purged, they will have been restored.
91 *
92 * If this call succeeds, it must be balanced by a call to
93 * AndroidBitmap_unlockPixels, after which time the address of the pixels should
94 * no longer be used.
95 *
96 * If this succeeds, *addrPtr will be set to the pixel address. If the call
97 * fails, addrPtr will be ignored.
98 */
99int AndroidBitmap_lockPixels(JNIEnv* env, jobject jbitmap, void** addrPtr);
100
101/**
102 * Call this to balance a successful call to AndroidBitmap_lockPixels.
103 */
104int AndroidBitmap_unlockPixels(JNIEnv* env, jobject jbitmap);
105
106#ifdef __cplusplus
107}
108#endif
109
110#endif
111
112/** @} */
113