1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Surface 18 * @{ 19 * 20 * @brief Provides the capabilities of applying for and releasing shared memory in multimedia and graphics scenarios. 21 * 22 * @since 1.0 23 * @version 1.0 24 */ 25 26 /** 27 * @file surface.h 28 * 29 * @brief Provides the capabilities of applying for and releasing shared memory in multimedia and graphics scenarios. 30 * 31 * By default, a surface can apply for a shared buffer. You can call {@link SetQueueSize} to set the maximum number 32 * of buffers that can be applied for. \n 33 * 34 * @since 1.0 35 * @version 1.0 36 */ 37 38 #ifndef GRAPHIC_LITE_SURFACE_H 39 #define GRAPHIC_LITE_SURFACE_H 40 41 #include "ibuffer_consumer_listener.h" 42 #include "surface_buffer.h" 43 #include "surface_type.h" 44 45 namespace OHOS { 46 /** 47 * @brief Defines the consumer listener used to notify consumers when the surface status is updated. 48 * 49 * @since 1.0 50 * @version 1.0 51 */ 52 class Surface { 53 public: 54 /** 55 * @brief A constructor used to create a {@link Surface} object for consumers to use. 56 * 57 * In multi-process scenarios, this function is provided for consumers to obtain buffers generated by producers 58 * for consumption. \n 59 * In single-process scenarios, this function can be used by both consumers and producers. \n 60 * 61 * @since 1.0 62 * @version 1.0 63 */ 64 static Surface* CreateSurface(); 65 66 /** 67 * @brief A destructor used to delete the <b>Surface</b> instance. 68 * 69 * This function releases the surface and all buffers applied for the surface. 70 * 71 * @since 1.0 72 * @version 1.0 73 */ 74 virtual ~Surface(); 75 76 /** 77 * @brief Sets the number of buffers that can be allocated to the surface. 78 * The default value is <b>1</b>. The value range is [1, 10]. 79 * 80 * @param queueSize Indicates the number of buffers to set. 81 * @since 1.0 82 * @version 1.0 83 */ 84 virtual void SetQueueSize(uint8_t queueSize) = 0; 85 86 /** 87 * @brief Obtains the number of surface buffers that can be allocated to the surface. 88 * The default value is <b>1</b>. The value range is [1, 10]. 89 * 90 * @return Returns the number of buffers. 91 * @since 1.0 92 * @version 1.0 93 */ 94 virtual uint8_t GetQueueSize() = 0; 95 96 /** 97 * @brief Sets the width and height of the surface for calculating its stride and size. 98 * The default value range of width and height is (0,7680]. 99 * 100 * @param width Indicates the surface width, in pixels. 101 * @param height Indicates the surface height, in pixels. 102 * @since 1.0 103 * @version 1.0 104 */ 105 virtual void SetWidthAndHeight(uint32_t width, uint32_t height) = 0; 106 107 /** 108 * @brief Obtains the width of the surface. 109 * 110 * @return Returns the surface width, in pixels. 111 * @since 1.0 112 * @version 1.0 */ 113 virtual uint32_t GetWidth() = 0; 114 115 /** 116 * @brief Obtains the height of the surface. 117 * 118 * @return Returns the surface height, in pixels. 119 * @since 1.0 120 * @version 1.0 121 */ 122 virtual uint32_t GetHeight() = 0; 123 124 /** 125 * @brief Sets the pixel format of the surface. For details, see {@link ImageFormat}. 126 * The default pixel format is {@link IMAGE_PIXEL_FORMAT_RGB565}. 127 * 128 * 129 * @param format Indicates the pixel format to be set. 130 * @since 1.0 131 * @version 1.0 132 */ 133 virtual void SetFormat(uint32_t format) = 0; 134 135 /** 136 * @brief Obtains the pixel format of the surface. For details, see {@link ImageFormat}. 137 * The default pixel format is {@link IMAGE_PIXEL_FORMAT_RGB565}. 138 * 139 * @return Returns the pixel format. 140 * @since 1.0 141 * @version 1.0 142 */ 143 virtual uint32_t GetFormat() = 0; 144 145 /** 146 * @brief Sets the number of bytes for stride alignment. 147 * 148 * By default, 4-byte aligned is used. The value range is [4,32]. 149 * 150 * @param strideAlignment Indicates the number of bytes for stride alignment. 151 * @since 1.0 152 * @version 1.0 153 */ 154 virtual void SetStrideAlignment(uint32_t strideAlignment) = 0; 155 156 /** 157 * @brief Obtains the number of bytes for stride alignment. By default, 4-byte aligned is used. 158 * 159 * @return Returns the number of bytes for stride alignment. 160 * @since 1.0 161 * @version 1.0 162 */ 163 virtual uint32_t GetStrideAlignment() = 0; 164 165 /** 166 * @brief Obtains the stride of the surface. 167 * 168 * @return Returns the stride. 169 * @since 1.0 170 * @version 1.0 171 */ 172 virtual uint32_t GetStride() = 0; 173 174 /** 175 * @brief Sets the size of the shared memory to allocate. 176 * 177 * 178 * @param size Indicates the size of the shared memory. The value range is (0,58982400]. 179 * @since 1.0 180 * @version 1.0 181 */ 182 virtual void SetSize(uint32_t size) = 0; 183 184 /** 185 * @brief Obtains the size of the shared memory to allocate. 186 * 187 * @return Returns the size of the shared memory. 188 * @since 1.0 189 * @version 1.0 190 */ 191 virtual uint32_t GetSize() = 0; 192 193 /** 194 * @brief Sets the usage scenario of the buffer. Physically contiguous memory and virtual memory (by default) 195 * are supported. By default, virtual memory is allocated. 196 * 197 * @param usage Indicates the usage scenario of the buffer. For details, see {@link BUFFER_CONSUMER_USAGE}. 198 * @since 1.0 199 * @version 1.0 200 */ 201 virtual void SetUsage(uint32_t usage) = 0; 202 203 /** 204 * @brief Obtains the usage scenario of the buffer. Physically contiguous memory and virtual memory are supported. 205 * 206 * @return Returns the usage scenario of the buffer. For details, see {@link BUFFER_CONSUMER_USAGE}. 207 * @since 1.0 208 * @version 1.0 209 */ 210 virtual uint32_t GetUsage() = 0; 211 212 /** 213 * @brief Sets surface user data, which is stored in the format of <key, value>. 214 * 215 * @param key Indicates the key of a key-value pair to store. 216 * @param value Indicates the value of the key-value pair to store. 217 * @since 1.0 218 * @version 1.0 219 */ 220 virtual void SetUserData(const std::string& key, const std::string& value) = 0; 221 222 /** 223 * @brief Obtains surface user data. 224 * 225 * @param key Indicates the key of a key-value pair for which the value is to be obtained. 226 * @return Returns the value of the key-value pair obtained. 227 * @since 1.0 228 * @version 1.0 229 */ 230 virtual std::string GetUserData(const std::string& key) = 0; 231 232 /** 233 * @brief Obtains a buffer to write data. 234 * 235 * 236 * @param wait Specifies whether the function waits for an available buffer. If <b>wait</b> is <b>1</b>, 237 * the function waits until there is an available buffer in the free queue before returning a pointer. 238 * If the <b>wait</b> is <b>0</b>, the function does not wait and returns <b>nullptr</b> if there is no buffer 239 * in the free queue. The default value is <b>0</b>. 240 * @return Returns the pointer to the buffer if the operation is successful; returns <b>nullptr</b> otherwise. 241 * @since 1.0 242 * @version 1.0 243 */ 244 virtual SurfaceBuffer* RequestBuffer(uint8_t wait = 0) = 0; 245 246 /** 247 * @brief Flushes a buffer to the dirty queue for consumers to use. 248 * 249 * 250 * 251 * @param SurfaceBuffer Indicates the pointer to the buffer flushed by producers. 252 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 253 * @since 1.0 254 * @version 1.0 255 */ 256 virtual int32_t FlushBuffer(SurfaceBuffer* buffer) = 0; 257 258 /** 259 * @brief Obtains a buffer. 260 * 261 * Consumers can use this function to obtain the buffer placed in the dirty queue by producers. 262 * If there is no buffer in the queue, <b>nullptr</b> is returned. 263 * 264 * @return Returns the pointer to the {@link SurfaceBuffer} object. 265 * @since 1.0 266 * @version 1.0 267 */ 268 virtual SurfaceBuffer* AcquireBuffer() = 0; 269 270 /** 271 * @brief Releases the consumed buffer. 272 * 273 * After a consumer has used a {@link SurfaceBuffer} object, the consumer can release it through 274 * {@link ReleaseBuffer}. The released object is placed into the free queue so that producers can 275 * apply for the object. 276 * 277 * @param SurfaceBuffer Indicates the pointer to the buffer released. 278 * @return Returns <b>true</b> if the buffer is released; returns <b>false</b> otherwise. 279 * @since 1.0 280 * @version 1.0 281 */ 282 virtual bool ReleaseBuffer(SurfaceBuffer* buffer) = 0; 283 284 /** 285 * @brief Releases a buffer to the free queue. 286 * 287 * 288 * @param SurfaceBuffer Indicates the pointer to the buffer to be released by producers. 289 * @since 1.0 290 * @version 1.0 291 */ 292 virtual void CancelBuffer(SurfaceBuffer* buffer) = 0; 293 294 /** 295 * @brief Registers a consumer listener. 296 * 297 * When a buffer is placed in the dirty queue, {@link OnBufferAvailable} is called to notify consumers. 298 * If the listener is repeatedly registered, only the latest one is retained. 299 * 300 * @param IBufferConsumerListener Indicates the listener to register. 301 * @since 1.0 302 * @version 1.0 303 */ 304 virtual void RegisterConsumerListener(IBufferConsumerListener& listener) = 0; 305 306 /** 307 * @brief Unregisters the consumer listener. 308 * 309 * After the listener is unregistered, no callback is triggered when a buffer is placed in the dirty queue. 310 * 311 * @since 1.0 312 * @version 1.0 313 */ 314 virtual void UnregisterConsumerListener() = 0; 315 316 protected: Surface()317 Surface() {} 318 }; 319 } // end namespace 320 #endif 321