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