1 /* 2 * Copyright (c) 2022 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 #ifndef NDK_INCLUDE_NATIVE_BUFFER_H_ 17 #define NDK_INCLUDE_NATIVE_BUFFER_H_ 18 19 /** 20 * @addtogroup OH_NativeBuffer 21 * @{ 22 * 23 * @brief Provides the native buffer capability. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 26 * @since 9 27 * @version 1.0 28 */ 29 30 /** 31 * @file native_buffer.h 32 * 33 * @brief Defines the functions for obtaining and using a native buffer. 34 * 35 * @library libnative_buffer.so 36 * @since 9 37 * @version 1.0 38 */ 39 40 #include <stdint.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 struct OH_NativeBuffer; 47 typedef struct OH_NativeBuffer OH_NativeBuffer; 48 49 /** 50 * @brief Indicates the usage of a native buffer. 51 * 52 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 53 * @since 10 54 * @version 1.0 55 */ 56 enum OH_NativeBuffer_Usage { 57 NATIVEBUFFER_USAGE_CPU_READ = (1ULL << 0), /// < CPU read buffer */ 58 NATIVEBUFFER_USAGE_CPU_WRITE = (1ULL << 1), /// < CPU write memory */ 59 NATIVEBUFFER_USAGE_MEM_DMA = (1ULL << 3), /// < Direct memory access (DMA) buffer */ 60 }; 61 62 /** 63 * @brief Indicates the format of a native buffer. 64 * 65 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 66 * @since 10 67 * @version 1.0 68 */ 69 enum OH_NativeBuffer_Format { 70 NATIVEBUFFER_PIXEL_FMT_RGB_565 = 3, /// < RGB565 format */ 71 NATIVEBUFFER_PIXEL_FMT_RGBA_5658, /// < RGBA5658 format */ 72 NATIVEBUFFER_PIXEL_FMT_RGBX_4444, /// < RGBX4444 format */ 73 NATIVEBUFFER_PIXEL_FMT_RGBA_4444, /// < RGBA4444 format */ 74 NATIVEBUFFER_PIXEL_FMT_RGB_444, /// < RGB444 format */ 75 NATIVEBUFFER_PIXEL_FMT_RGBX_5551, /// < RGBX5551 format */ 76 NATIVEBUFFER_PIXEL_FMT_RGBA_5551, /// < RGBA5551 format */ 77 NATIVEBUFFER_PIXEL_FMT_RGB_555, /// < RGB555 format */ 78 NATIVEBUFFER_PIXEL_FMT_RGBX_8888, /// < RGBX8888 format */ 79 NATIVEBUFFER_PIXEL_FMT_RGBA_8888, /// < RGBA8888 format */ 80 NATIVEBUFFER_PIXEL_FMT_RGB_888, /// < RGB888 format */ 81 NATIVEBUFFER_PIXEL_FMT_BGR_565, /// < BGR565 format */ 82 NATIVEBUFFER_PIXEL_FMT_BGRX_4444, /// < BGRX4444 format */ 83 NATIVEBUFFER_PIXEL_FMT_BGRA_4444, /// < BGRA4444 format */ 84 NATIVEBUFFER_PIXEL_FMT_BGRX_5551, /// < BGRX5551 format */ 85 NATIVEBUFFER_PIXEL_FMT_BGRA_5551, /// < BGRA5551 format */ 86 NATIVEBUFFER_PIXEL_FMT_BGRX_8888, /// < BGRX8888 format */ 87 NATIVEBUFFER_PIXEL_FMT_BGRA_8888, /// < BGRA8888 format */ 88 NATIVEBUFFER_PIXEL_FMT_BUTT = 0X7FFFFFFF /// < Invalid pixel format */ 89 }; 90 91 /** 92 * @brief Indicates the color space of a native buffer. 93 * 94 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 95 * @since 11 96 * @version 1.0 97 */ 98 enum OH_NativeBuffer_ColorSpace { 99 /** None color space */ 100 OH_COLORSPACE_NONE, 101 /** COLORPRIMARIES_BT601_P | (TRANSFUNC_BT709 << 8) | (MATRIX_BT601_P << 16) | (RANGE_FULL << 21) */ 102 OH_COLORSPACE_BT601_EBU_FULL, 103 /** COLORPRIMARIES_BT601_N | (TRANSFUNC_BT709 << 8) | (MATRIX_BT601_N << 16) | (RANGE_FULL << 21)*/ 104 OH_COLORSPACE_BT601_SMPTE_C_FULL, 105 /** COLORPRIMARIES_BT709 | (TRANSFUNC_BT709 << 8) | (MATRIX_BT709 << 16) | (RANGE_FULL << 21) */ 106 OH_COLORSPACE_BT709_FULL, 107 /** COLORPRIMARIES_BT2020 | (TRANSFUNC_HLG << 8) | (MATRIX_BT2020 << 16) | (RANGE_FULL << 21) */ 108 OH_COLORSPACE_BT2020_HLG_FULL, 109 /** COLORPRIMARIES_BT2020 | (TRANSFUNC_PQ << 8) | (MATRIX_BT2020 << 16) | (RANGE_FULL << 21) */ 110 OH_COLORSPACE_BT2020_PQ_FULL, 111 /** COLORPRIMARIES_BT601_P | (TRANSFUNC_BT709 << 8) | (MATRIX_BT601_P << 16) | (RANGE_LIMITED << 21) */ 112 OH_COLORSPACE_BT601_EBU_LIMIT, 113 /** COLORPRIMARIES_BT601_N | (TRANSFUNC_BT709 << 8) | (MATRIX_BT601_N << 16) | (RANGE_LIMITED << 21) */ 114 OH_COLORSPACE_BT601_SMPTE_C_LIMIT, 115 /** COLORPRIMARIES_BT709 | (TRANSFUNC_BT709 << 8) | (MATRIX_BT709 << 16) | (RANGE_LIMITED << 21) */ 116 OH_COLORSPACE_BT709_LIMIT, 117 /** COLORPRIMARIES_BT2020 | (TRANSFUNC_HLG << 8) | (MATRIX_BT2020 << 16) | (RANGE_LIMITED << 21) */ 118 OH_COLORSPACE_BT2020_HLG_LIMIT, 119 /** COLORPRIMARIES_BT2020 | (TRANSFUNC_PQ << 8) | (MATRIX_BT2020 << 16) | (RANGE_LIMITED << 21) */ 120 OH_COLORSPACE_BT2020_PQ_LIMIT, 121 /** COLORPRIMARIES_SRGB | (TRANSFUNC_SRGB << 8) | (MATRIX_BT601_N << 16) | (RANGE_FULL << 21) */ 122 OH_COLORSPACE_SRGB_FULL, 123 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_SRGB << 8) | (MATRIX_P3 << 16) | (RANGE_FULL << 21) */ 124 OH_COLORSPACE_P3_FULL, 125 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_HLG << 8) | (MATRIX_P3 << 16) | (RANGE_FULL << 21) */ 126 OH_COLORSPACE_P3_HLG_FULL, 127 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_PQ << 8) | (MATRIX_P3 << 16) | (RANGE_FULL << 21) */ 128 OH_COLORSPACE_P3_PQ_FULL, 129 /** COLORPRIMARIES_ADOBERGB | (TRANSFUNC_ADOBERGB << 8) | (MATRIX_ADOBERGB << 16) | (RANGE_FULL << 21) */ 130 OH_COLORSPACE_ADOBERGB_FULL, 131 /** COLORPRIMARIES_SRGB | (TRANSFUNC_SRGB << 8) | (MATRIX_BT601_N << 16) | (RANGE_LIMITED << 21) */ 132 OH_COLORSPACE_SRGB_LIMIT, 133 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_SRGB << 8) | (MATRIX_P3 << 16) | (RANGE_LIMITED << 21) */ 134 OH_COLORSPACE_P3_LIMIT, 135 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_HLG << 8) | (MATRIX_P3 << 16) | (RANGE_LIMITED << 21) */ 136 OH_COLORSPACE_P3_HLG_LIMIT, 137 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_PQ << 8) | (MATRIX_P3 << 16) | (RANGE_LIMITED << 21) */ 138 OH_COLORSPACE_P3_PQ_LIMIT, 139 /** COLORPRIMARIES_ADOBERGB | (TRANSFUNC_ADOBERGB << 8) | (MATRIX_ADOBERGB << 16) | (RANGE_LIMITED << 21) */ 140 OH_COLORSPACE_ADOBERGB_LIMIT, 141 /** COLORPRIMARIES_SRGB | (TRANSFUNC_LINEAR << 8) */ 142 OH_COLORSPACE_LINEAR_SRGB, 143 /** equal to OH_COLORSPACE_LINEAR_SRGB */ 144 OH_COLORSPACE_LINEAR_BT709, 145 /** COLORPRIMARIES_P3_D65 | (TRANSFUNC_LINEAR << 8) */ 146 OH_COLORSPACE_LINEAR_P3, 147 /** COLORPRIMARIES_BT2020 | (TRANSFUNC_LINEAR << 8) */ 148 OH_COLORSPACE_LINEAR_BT2020, 149 /** equal to OH_COLORSPACE_SRGB_FULL */ 150 OH_COLORSPACE_DISPLAY_SRGB, 151 /** equal to OH_COLORSPACE_P3_FULL */ 152 OH_COLORSPACE_DISPLAY_P3_SRGB, 153 /** equal to OH_COLORSPACE_P3_HLG_FULL */ 154 OH_COLORSPACE_DISPLAY_P3_HLG, 155 /** equal to OH_COLORSPACE_P3_PQ_FULL */ 156 OH_COLORSPACE_DISPLAY_P3_PQ, 157 /** COLORPRIMARIES_BT2020 | (TRANSFUNC_SRGB << 8) | (MATRIX_BT2020 << 16) | (RANGE_FULL << 21) */ 158 OH_COLORSPACE_DISPLAY_BT2020_SRGB, 159 /** equal to OH_COLORSPACE_BT2020_HLG_FULL */ 160 OH_COLORSPACE_DISPLAY_BT2020_HLG, 161 /** equal to OH_COLORSPACE_BT2020_PQ_FULL */ 162 OH_COLORSPACE_DISPLAY_BT2020_PQ, 163 }; 164 165 /** 166 * @brief <b>OH_NativeBuffer</b> config. \n 167 * Used to allocating new <b>OH_NativeBuffer</b> andquery parameters if existing ones. 168 * 169 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 170 * @since 9 171 * @version 1.0 172 */ 173 typedef struct { 174 int32_t width; ///< Width in pixels 175 int32_t height; ///< Height in pixels 176 int32_t format; ///< One of PixelFormat 177 int32_t usage; ///< Combination of buffer usage 178 int32_t stride; ///< the stride of memory 179 } OH_NativeBuffer_Config; 180 181 /** 182 * @brief Alloc a <b>OH_NativeBuffer</b> that matches the passed BufferRequestConfig. \n 183 * A new <b>OH_NativeBuffer</b> instance is created each time this function is called. 184 * 185 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 186 * @param config Indicates the pointer to a <b>BufferRequestConfig</b> instance. 187 * @return Returns the pointer to the <b>OH_NativeBuffer</b> instance created if the operation is successful, \n 188 * returns <b>NULL</b> otherwise. 189 * @since 9 190 * @version 1.0 191 */ 192 OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config); 193 194 /** 195 * @brief Adds the reference count of a OH_NativeBuffer. 196 * 197 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 198 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 199 * @return Returns an error code, 0 is success, otherwise, failed. 200 * @since 9 201 * @version 1.0 202 */ 203 int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer); 204 205 /** 206 * @brief Decreases the reference count of a OH_NativeBuffer and, when the reference count reaches 0, \n 207 * destroys this OH_NativeBuffer. 208 * 209 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 210 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 211 * @return Returns an error code, 0 is success, otherwise, failed. 212 * @since 9 213 * @version 1.0 214 */ 215 int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer); 216 217 /** 218 * @brief Return a config of the OH_NativeBuffer in the passed OHNativeBufferConfig struct. 219 * 220 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 221 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 222 * @param config Indicates the pointer to the <b>NativeBufferConfig</b> of the buffer. 223 * @return <b>void</b> 224 * @since 9 225 * @version 1.0 226 */ 227 void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config); 228 229 /** 230 * @brief Provide direct cpu access to the OH_NativeBuffer in the process's address space. 231 * 232 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 233 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 234 * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory. 235 * @return Returns an error code, 0 is success, otherwise, failed. 236 * @since 9 237 * @version 1.0 238 */ 239 240 int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr); 241 242 /** 243 * @brief Remove direct cpu access ability of the OH_NativeBuffer in the process's address space. 244 * 245 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 246 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 247 * @return Returns an error code, 0 is success, otherwise, failed. 248 * @since 9 249 * @version 1.0 250 */ 251 int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer); 252 253 /** 254 * @brief Get the systen wide unique sequence number of the OH_NativeBuffer. 255 * 256 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 257 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 258 * @return Returns the sequence number, which is unique for each OH_NativeBuffer. 259 * @since 9 260 * @version 1.0 261 */ 262 uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer); 263 264 /** 265 * @brief Set the color space of the OH_NativeBuffer. 266 * 267 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 268 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 269 * @param colorSpace Indicates the color space of native buffer, see <b>OH_NativeBuffer_ColorSpace</b>. 270 * @return Returns the sequence number, which is unique for each OH_NativeBuffer. 271 * @since 11 272 * @version 1.0 273 */ 274 int32_t OH_NativeBuffer_SetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace colorSpace); 275 #ifdef __cplusplus 276 } 277 #endif 278 279 /** @} */ 280 #endif