1/*
2 * Copyright (C) 2013 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#ifndef ANDROID_HWUI_PIXEL_BUFFER_H
18#define ANDROID_HWUI_PIXEL_BUFFER_H
19
20#include <GLES3/gl3.h>
21#include <cutils/log.h>
22
23namespace android {
24namespace uirenderer {
25
26/**
27 * Represents a pixel buffer. A pixel buffer will be backed either by a
28 * PBO on OpenGL ES 3.0 and higher or by an array of uint8_t on other
29 * versions. If the buffer is backed by a PBO it will of type
30 * GL_PIXEL_UNPACK_BUFFER.
31 *
32 * To read from or write into a PixelBuffer you must first map the
33 * buffer using the map(AccessMode) method. This method returns a
34 * pointer to the beginning of the buffer.
35 *
36 * Before the buffer can be used by the GPU, for instance to upload
37 * a texture, you must first unmap the buffer. To do so, call the
38 * unmap() method.
39 *
40 * Mapping and unmapping a PixelBuffer can have the side effect of
41 * changing the currently active GL_PIXEL_UNPACK_BUFFER. It is
42 * therefore recommended to call Caches::unbindPixelbuffer() after
43 * using a PixelBuffer to upload to a texture.
44 */
45class PixelBuffer {
46public:
47    enum BufferType {
48        kBufferType_Auto,
49        kBufferType_CPU
50    };
51
52    enum AccessMode {
53        kAccessMode_None = 0,
54        kAccessMode_Read = GL_MAP_READ_BIT,
55        kAccessMode_Write = GL_MAP_WRITE_BIT,
56        kAccessMode_ReadWrite = GL_MAP_READ_BIT | GL_MAP_WRITE_BIT
57    };
58
59    /**
60     * Creates a new PixelBuffer object with the specified format and
61     * dimensions. The buffer is immediately allocated.
62     *
63     * The buffer type specifies how the buffer should be allocated.
64     * By default this method will automatically choose whether to allocate
65     * a CPU or GPU buffer.
66     */
67    static PixelBuffer* create(GLenum format, uint32_t width, uint32_t height,
68            BufferType type = kBufferType_Auto);
69
70    virtual ~PixelBuffer() {
71    }
72
73    /**
74     * Returns the format of this render buffer.
75     */
76    GLenum getFormat() const {
77        return mFormat;
78    }
79
80    /**
81     * Maps this before with the specified access mode. This method
82     * returns a pointer to the region of memory where the buffer was
83     * mapped.
84     *
85     * If the buffer is already mapped when this method is invoked,
86     * this method will return the previously mapped pointer. The
87     * access mode can only be changed by calling unmap() first.
88     *
89     * The specified access mode cannot be kAccessMode_None.
90     */
91    virtual uint8_t* map(AccessMode mode = kAccessMode_ReadWrite) = 0;
92
93    /**
94     * Unmaps this buffer, if needed. After the buffer is unmapped,
95     * the pointer previously returned by map() becomes invalid and
96     * should not be used. After calling this method, getMappedPointer()
97     * will always return NULL.
98     */
99    virtual void unmap() = 0;
100
101    /**
102     * Returns the current access mode for this buffer. If the buffer
103     * is not mapped, this method returns kAccessMode_None.
104     */
105    AccessMode getAccessMode() const {
106        return mAccessMode;
107    }
108
109    /**
110     * Returns the currently mapped pointer. Returns NULL if the buffer
111     * is not mapped.
112     */
113    virtual uint8_t* getMappedPointer() const = 0;
114
115    /**
116     * Upload the specified rectangle of this pixel buffer as a
117     * GL_TEXTURE_2D texture. Calling this method will trigger
118     * an unmap() if necessary.
119     */
120    virtual void upload(uint32_t x, uint32_t y, uint32_t width, uint32_t height, int offset) = 0;
121
122    /**
123     * Upload the specified rectangle of this pixel buffer as a
124     * GL_TEXTURE_2D texture. Calling this method will trigger
125     * an unmap() if necessary.
126     *
127     * This is a convenience function provided to save callers the
128     * trouble of computing the offset parameter.
129     */
130    void upload(uint32_t x, uint32_t y, uint32_t width, uint32_t height) {
131        upload(x, y, width, height, getOffset(x, y));
132    }
133
134    /**
135     * Returns the width of the render buffer in pixels.
136     */
137    uint32_t getWidth() const {
138        return mWidth;
139    }
140
141    /**
142     * Returns the height of the render buffer in pixels.
143     */
144    uint32_t getHeight() const {
145        return mHeight;
146    }
147
148    /**
149     * Returns the size of this pixel buffer in bytes.
150     */
151    uint32_t getSize() const {
152        return mWidth * mHeight * formatSize(mFormat);
153    }
154
155    /**
156     * Returns the offset of a pixel in this pixel buffer, in bytes.
157     */
158    uint32_t getOffset(uint32_t x, uint32_t y) const {
159        return (y * mWidth + x) * formatSize(mFormat);
160    }
161
162    /**
163     * Returns the number of bytes per pixel in the specified format.
164     *
165     * Supported formats:
166     *      GL_ALPHA
167     *      GL_RGBA
168     */
169    static uint32_t formatSize(GLenum format) {
170        switch (format) {
171            case GL_ALPHA:
172                return 1;
173            case GL_RGBA:
174                return 4;
175        }
176        return 0;
177    }
178
179    /**
180     * Returns the alpha channel offset in the specified format.
181     *
182     * Supported formats:
183     *      GL_ALPHA
184     *      GL_RGBA
185     */
186    static uint32_t formatAlphaOffset(GLenum format) {
187        switch (format) {
188            case GL_ALPHA:
189                return 0;
190            case GL_RGBA:
191                return 3;
192        }
193
194        ALOGE("unsupported format: %d",format);
195        return 0;
196    }
197
198protected:
199    /**
200     * Creates a new render buffer in the specified format and dimensions.
201     * The format must be GL_ALPHA or GL_RGBA.
202     */
203    PixelBuffer(GLenum format, uint32_t width, uint32_t height):
204            mFormat(format), mWidth(width), mHeight(height), mAccessMode(kAccessMode_None) {
205    }
206
207    GLenum mFormat;
208
209    uint32_t mWidth;
210    uint32_t mHeight;
211
212    AccessMode mAccessMode;
213
214}; // class PixelBuffer
215
216}; // namespace uirenderer
217}; // namespace android
218
219#endif // ANDROID_HWUI_PIXEL_BUFFER_H
220