• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 namespace android {
23 namespace 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  */
44 class PixelBuffer {
45 public:
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 
~PixelBuffer()69     virtual ~PixelBuffer() {
70     }
71 
72     /**
73      * Returns the format of this render buffer.
74      */
getFormat()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      */
getAccessMode()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      */
upload(uint32_t x,uint32_t y,uint32_t width,uint32_t height)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      */
getWidth()136     uint32_t getWidth() const {
137         return mWidth;
138     }
139 
140     /**
141      * Returns the height of the render buffer in pixels.
142      */
getHeight()143     uint32_t getHeight() const {
144         return mHeight;
145     }
146 
147     /**
148      * Returns the size of this pixel buffer in bytes.
149      */
getSize()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      */
getOffset(uint32_t x,uint32_t y)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      */
formatSize(GLenum format)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 
178 protected:
179     /**
180      * Creates a new render buffer in the specified format and dimensions.
181      * The format must be GL_ALPHA or GL_RGBA.
182      */
PixelBuffer(GLenum format,uint32_t width,uint32_t height)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