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 * @since 9 36 * @version 1.0 37 */ 38 39 #include <stdint.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 struct OH_NativeBuffer; 46 typedef struct OH_NativeBuffer OH_NativeBuffer; 47 48 /** 49 * @brief Indicates the usage of a native buffer. 50 * 51 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 52 * @since 10 53 * @version 1.0 54 */ 55 enum OH_NativeBuffer_Usage { 56 NATIVEBUFFER_USAGE_CPU_READ = (1ULL << 0), /// < CPU read buffer */ 57 NATIVEBUFFER_USAGE_CPU_WRITE = (1ULL << 1), /// < CPU write memory */ 58 NATIVEBUFFER_USAGE_MEM_DMA = (1ULL << 3), /// < Direct memory access (DMA) buffer */ 59 }; 60 61 /** 62 * @brief Indicates the format of a native buffer. 63 * 64 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 65 * @since 10 66 * @version 1.0 67 */ 68 enum OH_NativeBuffer_Format { 69 NATIVEBUFFER_PIXEL_FMT_RGB_565 = 3, /// < RGB565 format */ 70 NATIVEBUFFER_PIXEL_FMT_RGBA_5658, /// < RGBA5658 format */ 71 NATIVEBUFFER_PIXEL_FMT_RGBX_4444, /// < RGBX4444 format */ 72 NATIVEBUFFER_PIXEL_FMT_RGBA_4444, /// < RGBA4444 format */ 73 NATIVEBUFFER_PIXEL_FMT_RGB_444, /// < RGB444 format */ 74 NATIVEBUFFER_PIXEL_FMT_RGBX_5551, /// < RGBX5551 format */ 75 NATIVEBUFFER_PIXEL_FMT_RGBA_5551, /// < RGBA5551 format */ 76 NATIVEBUFFER_PIXEL_FMT_RGB_555, /// < RGB555 format */ 77 NATIVEBUFFER_PIXEL_FMT_RGBX_8888, /// < RGBX8888 format */ 78 NATIVEBUFFER_PIXEL_FMT_RGBA_8888, /// < RGBA8888 format */ 79 NATIVEBUFFER_PIXEL_FMT_RGB_888, /// < RGB888 format */ 80 NATIVEBUFFER_PIXEL_FMT_BGR_565, /// < BGR565 format */ 81 NATIVEBUFFER_PIXEL_FMT_BGRX_4444, /// < BGRX4444 format */ 82 NATIVEBUFFER_PIXEL_FMT_BGRA_4444, /// < BGRA4444 format */ 83 NATIVEBUFFER_PIXEL_FMT_BGRX_5551, /// < BGRX5551 format */ 84 NATIVEBUFFER_PIXEL_FMT_BGRA_5551, /// < BGRA5551 format */ 85 NATIVEBUFFER_PIXEL_FMT_BGRX_8888, /// < BGRX8888 format */ 86 NATIVEBUFFER_PIXEL_FMT_BGRA_8888, /// < BGRA8888 format */ 87 NATIVEBUFFER_PIXEL_FMT_BUTT = 0X7FFFFFFF /// < Invalid pixel format */ 88 }; 89 90 /** 91 * @brief <b>OH_NativeBuffer</b> config. \n 92 * Used to allocating new <b>OH_NativeBuffer</b> andquery parameters if existing ones. 93 * 94 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 95 * @since 9 96 * @version 1.0 97 */ 98 typedef struct { 99 int32_t width; ///< Width in pixels 100 int32_t height; ///< Height in pixels 101 int32_t format; ///< One of PixelFormat 102 int32_t usage; ///< Combination of buffer usage 103 int32_t stride; ///< the stride of memory 104 } OH_NativeBuffer_Config; 105 106 /** 107 * @brief Alloc a <b>OH_NativeBuffer</b> that matches the passed BufferRequestConfig. \n 108 * A new <b>OH_NativeBuffer</b> instance is created each time this function is called. 109 * 110 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 111 * @param config Indicates the pointer to a <b>BufferRequestConfig</b> instance. 112 * @return Returns the pointer to the <b>OH_NativeBuffer</b> instance created if the operation is successful, \n 113 * returns <b>NULL</b> otherwise. 114 * @since 9 115 * @version 1.0 116 */ 117 OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config); 118 119 /** 120 * @brief Adds the reference count of a OH_NativeBuffer. 121 * 122 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 123 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 124 * @return Returns an error code, 0 is success, otherwise, failed. 125 * @since 9 126 * @version 1.0 127 */ 128 int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer); 129 130 /** 131 * @brief Decreases the reference count of a OH_NativeBuffer and, when the reference count reaches 0, \n 132 * destroys this OH_NativeBuffer. 133 * 134 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 135 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 136 * @return Returns an error code, 0 is success, otherwise, failed. 137 * @since 9 138 * @version 1.0 139 */ 140 int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer); 141 142 /** 143 * @brief Return a config of the OH_NativeBuffer in the passed OHNativeBufferConfig struct. 144 * 145 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 146 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 147 * @param config Indicates the pointer to the <b>NativeBufferConfig</b> of the buffer. 148 * @return <b>void</b> 149 * @since 9 150 * @version 1.0 151 */ 152 void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config); 153 154 /** 155 * @brief Provide direct cpu access to the OH_NativeBuffer in the process's address space. 156 * 157 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 158 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 159 * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory. 160 * @return Returns an error code, 0 is success, otherwise, failed. 161 * @since 9 162 * @version 1.0 163 */ 164 165 int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr); 166 167 /** 168 * @brief Remove direct cpu access ability of the OH_NativeBuffer in the process's address space. 169 * 170 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 171 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 172 * @return Returns an error code, 0 is success, otherwise, failed. 173 * @since 9 174 * @version 1.0 175 */ 176 int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer); 177 178 /** 179 * @brief Get the systen wide unique sequence number of the OH_NativeBuffer. 180 * 181 * @syscap SystemCapability.Graphic.Graphic2D.NativeBuffer 182 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 183 * @return Returns the sequence number, which is unique for each OH_NativeBuffer. 184 * @since 9 185 * @version 1.0 186 */ 187 uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer); 188 189 #ifdef __cplusplus 190 } 191 #endif 192 193 /** @} */ 194 #endif