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.OH_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 <b>OH_NativeBuffer</b> config. \n 50 * Used to allocating new <b>OH_NativeBuffer</b> andquery parameters if existing ones. 51 * 52 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 53 * @since 9 54 * @version 1.0 55 */ 56 typedef struct { 57 int32_t width; ///< Width in pixels 58 int32_t height; ///< Height in pixels 59 int32_t format; ///< One of PixelFormat 60 int32_t usage; ///< Combination of buffer usage 61 } OH_NativeBuffer_Config; 62 63 /** 64 * @brief Alloc a <b>OH_NativeBuffer</b> that matches the passed BufferRequestConfig. \n 65 * A new <b>OH_NativeBuffer</b> instance is created each time this function is called. 66 * 67 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 68 * @param config Indicates the pointer to a <b>BufferRequestConfig</b> instance. 69 * @return Returns the pointer to the <b>OH_NativeBuffer</b> instance created if the operation is successful, \n 70 * returns <b>NULL</b> otherwise. 71 * @since 9 72 * @version 1.0 73 */ 74 OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config); 75 76 /** 77 * @brief Adds the reference count of a OH_NativeBuffer. 78 * 79 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 80 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 81 * @return Returns an error code defined in <b>GSError</b>. 82 * @since 9 83 * @version 1.0 84 */ 85 int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer); 86 87 /** 88 * @brief Decreases the reference count of a OH_NativeBuffer and, when the reference count reaches 0, \n 89 * destroys this OH_NativeBuffer. 90 * 91 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 92 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 93 * @return Returns an error code defined in <b>GSError</b>. 94 * @since 9 95 * @version 1.0 96 */ 97 int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer); 98 99 /** 100 * @brief Return a config of the OH_NativeBuffer in the passed OHNativeBufferConfig struct. 101 * 102 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 103 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 104 * @param config Indicates the pointer to the <b>NativeBufferConfig</b> of the buffer. 105 * @return Returns the pointer to the <b>BufferRequestConfig</b> instance if the operation is successful, \n 106 * returns <b>NULL</b> otherwise. 107 * @since 9 108 * @version 1.0 109 */ 110 void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config); 111 112 /** 113 * @brief Provide direct cpu access to the OH_NativeBuffer in the process's address space. 114 * 115 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 116 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 117 * @param virAddr Indicates the address of the <b>OH_NativeBuffer</b> in virtual memory. 118 * @return Returns an error code defined in <b>GSError</b>. 119 * @since 9 120 * @version 1.0 121 */ 122 123 int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr); 124 125 /** 126 * @brief Remove direct cpu access ability of the OH_NativeBuffer in the process's address space. 127 * 128 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 129 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 130 * @return Returns an error code defined in <b>GSError</b>. 131 * @since 9 132 * @version 1.0 133 */ 134 int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer); 135 136 /** 137 * @brief Get the systen wide unique sequence number of the OH_NativeBuffer. 138 * 139 * @syscap SystemCapability.Graphic.Graphic2D.OH_NativeBuffer 140 * @param buffer Indicates the pointer to a <b>OH_NativeBuffer</b> instance. 141 * @return Returns the sequence number, which is unique for each OH_NativeBuffer. 142 * @since 9 143 * @version 1.0 144 */ 145 uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer); 146 147 #ifdef __cplusplus 148 } 149 #endif 150 151 /** @} */ 152 #endif