1 /* 2 * Copyright (c) 2021-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_EXTERNAL_NATIVE_WINDOW_H_ 17 #define NDK_INCLUDE_EXTERNAL_NATIVE_WINDOW_H_ 18 19 /** 20 * @addtogroup NativeWindow 21 * @{ 22 * 23 * @brief Provides the native window capability for connection to the EGL. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 26 * @since 8 27 * @version 1.0 28 */ 29 30 /** 31 * @file external_window.h 32 * 33 * @brief Defines the functions for obtaining and using a native window. 34 * 35 * @since 8 36 * @version 1.0 37 */ 38 39 #include "window.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Creates a <b>NativeWindow</b> instance. A new <b>NativeWindow</b> instance is created each time this function is called. 47 * 48 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 49 * @param pSurface Indicates the pointer to a <b>ProduceSurface</b>. The type is a pointer to <b>sptr<OHOS::Surface></b>. 50 * @return Returns the pointer to the <b>NativeWindow</b> instance created. 51 * @since 8 52 * @version 1.0 53 */ 54 struct NativeWindow* OH_NativeWindow_CreateNativeWindow(void* pSurface); 55 56 /** 57 * @brief Decreases the reference count of a <b>NativeWindow</b> instance by 1, and when the reference count reaches 0, destroys the instance. 58 * 59 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 60 * @param window Indicates the pointer to a <b>NativeWindow</b> instance. 61 * @since 8 62 * @version 1.0 63 */ 64 void OH_NativeWindow_DestroyNativeWindow(struct NativeWindow* window); 65 66 /** 67 * @brief Creates a <b>NativeWindowBuffer</b> instance. A new <b>NativeWindowBuffer</b> instance is created each time this function is called. 68 * 69 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 70 * @param pSurfaceBuffer Indicates the pointer to a produce buffer. The type is <b>sptr<OHOS::SurfaceBuffer></b>. 71 * @return Returns the pointer to the <b>NativeWindowBuffer</b> instance created. 72 * @since 8 73 * @version 1.0 74 */ 75 struct NativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer(void* pSurfaceBuffer); 76 77 /** 78 * @brief Decreases the reference count of a <b>NativeWindowBuffer</b> instance by 1 and, when the reference count reaches 0, destroys the instance. 79 * 80 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 81 * @param buffer Indicates the pointer to a <b>NativeWindowBuffer</b> instance. 82 * @since 8 83 * @version 1.0 84 */ 85 void OH_NativeWindow_DestroyNativeWindowBuffer(struct NativeWindowBuffer* buffer); 86 87 /** 88 * @brief Requests a <b>NativeWindowBuffer</b> through a <b>NativeWindow</b> instance for content production. 89 * 90 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 91 * @param window Indicates the pointer to a <b>NativeWindow</b> instance. 92 * @param buffer Indicates the double pointer to a <b>NativeWindowBuffer</b> instance. 93 * @param fenceFd Indicates the pointer to a file descriptor handle. 94 * @return Returns an error code defined in <b>GSError</b>. 95 * @since 8 96 * @version 1.0 97 */ 98 int32_t OH_NativeWindow_NativeWindowRequestBuffer(struct NativeWindow *window, 99 struct NativeWindowBuffer **buffer, int *fenceFd); 100 101 /** 102 * @brief Flushes the <b>NativeWindowBuffer</b> filled with the content to the buffer queue through a <b>NativeWindow</b> instance for content consumption. 103 * 104 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 105 * @param window Indicates the pointer to a <b>NativeWindow</b> instance. 106 * @param buffer Indicates the pointer to a <b>NativeWindowBuffer</b> instance. 107 * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. 108 * @param region Indicates a dirty region where content is updated. 109 * @return Returns an error code defined in <b>GSError</b>. 110 * @since 8 111 * @version 1.0 112 */ 113 int32_t OH_NativeWindow_NativeWindowFlushBuffer(struct NativeWindow *window, struct NativeWindowBuffer *buffer, 114 int fenceFd, Region region); 115 116 /** 117 * @brief Returns the <b>NativeWindowBuffer</b> to the buffer queue through a <b>NativeWindow</b> instance, without filling in any content. The <b>NativeWindowBuffer</b> can be used for another request. 118 * 119 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 120 * @param window Indicates the pointer to a <b>NativeWindow</b> instance. 121 * @param buffer Indicates the pointer to a <b>NativeWindowBuffer</b> instance. 122 * @return Returns an error code defined in <b>GSError</b>. 123 * @since 8 124 * @version 1.0 125 */ 126 int32_t OH_NativeWindow_NativeWindowAbortBuffer(struct NativeWindow *window, struct NativeWindowBuffer *buffer); 127 128 /** 129 * @brief Sets or obtains the attributes of a native window, including the width, height, and content format. 130 * 131 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 132 * @param window Indicates the pointer to a <b>NativeWindow</b> instance. 133 * @param code Indicates the operation code. 134 * @return Returns an error code defined in <b>GSError</b>. 135 * @since 8 136 * @version 1.0 137 */ 138 int32_t OH_NativeWindow_NativeWindowHandleOpt(struct NativeWindow *window, int code, ...); 139 140 /** 141 * @brief Obtains the pointer to a <b>BufferHandle</b> of a <b>NativeWindowBuffer</b> instance. 142 * 143 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 144 * @param buffer Indicates the pointer to a <b>NativeWindowBuffer</b> instance. 145 * @return Returns the pointer to the <b>BufferHandle</b> instance obtained. 146 * @since 8 147 * @version 1.0 148 */ 149 BufferHandle *OH_NativeWindow_GetBufferHandleFromNative(struct NativeWindowBuffer *buffer); 150 151 /** 152 * @brief Adds the reference count of a native object. 153 * 154 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 155 * @param obj Indicates the pointer to a <b>NativeWindow</b> or <b>NativeWindowBuffer</b> instance. 156 * @return Returns an error code defined in <b>GSError</b>. 157 * @since 8 158 * @version 1.0 159 */ 160 int32_t OH_NativeWindow_NativeObjectReference(void *obj); 161 162 /** 163 * @brief Decreases the reference count of a native object and, when the reference count reaches 0, destroys this object. 164 * 165 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 166 * @param obj Indicates the pointer to a <b>NativeWindow</b> or <b>NativeWindowBuffer</b> instance. 167 * @return Returns an error code defined in <b>GSError</b>. 168 * @since 8 169 * @version 1.0 170 */ 171 int32_t OH_NativeWindow_NativeObjectUnreference(void *obj); 172 173 /** 174 * @brief Obtains the magic ID of a native object. 175 * 176 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 177 * @param obj Indicates the pointer to a <b>NativeWindow</b> or <b>NativeWindowBuffer</b> instance. 178 * @return Returns the magic ID, which is unique for each native object. 179 * @since 8 180 * @version 1.0 181 */ 182 int32_t OH_NativeWindow_GetNativeObjectMagic(void *obj); 183 184 #ifdef __cplusplus 185 } 186 #endif 187 188 /** @} */ 189 #endif 190