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