1 /* 2 * Copyright (c) 2022-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 /** 17 * @addtogroup NativeVsync 18 * @{ 19 * 20 * @brief Provides the native vsync capability. 21 * 22 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 23 * @since 9 24 * @version 1.0 25 */ 26 27 /** 28 * @file native_vsync.h 29 * 30 * @brief Defines the functions for obtaining and using a native vsync. 31 * 32 * @kit ArkGraphics2D 33 * @library libnative_vsync.so 34 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 35 * @since 9 36 * @version 1.0 37 */ 38 39 #ifndef NDK_INCLUDE_NATIVE_VSYNC_H_ 40 #define NDK_INCLUDE_NATIVE_VSYNC_H_ 41 42 #include <stdint.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 struct OH_NativeVSync; 49 typedef struct OH_NativeVSync OH_NativeVSync; 50 typedef void (*OH_NativeVSync_FrameCallback)(long long timestamp, void *data); 51 52 /** 53 * @brief Defines the expected frame rate range struct. 54 * 55 * @since 20 56 * @version 1.0 57 */ 58 typedef struct { 59 /**The minimum frame rate of dynamical callback rate range. */ 60 int32_t min; 61 /**The maximum frame rate of dynamical callback rate range. */ 62 int32_t max; 63 /**The expected frame rate of dynamical callback rate range. */ 64 int32_t expected; 65 } OH_NativeVSync_ExpectedRateRange; 66 67 /** 68 * @brief Creates a <b>NativeVsync</b> instance.\n 69 * A new <b>NativeVsync</b> instance is created each time this function is called. 70 * 71 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 72 * @param name Indicates the vsync connection name. 73 * @param length Indicates the name's length. 74 * @return Returns the pointer to the <b>NativeVsync</b> instance created. 75 * @since 9 76 * @version 1.0 77 */ 78 OH_NativeVSync* OH_NativeVSync_Create(const char* name, unsigned int length); 79 80 /** 81 * @brief Destroys an <b>OH_NativeVSync</b> instance. 82 * Once the <b>OH_NativeVSync</b> pointer is destroyed, it must not be used to prevent dangling pointer problems. 83 * Pay special attention to the management of the <b>OH_NativeVSync</b> pointer in concurrent multithreaded scenarios. 84 * 85 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 86 * @param nativeVsync Pointer to an <b>OH_NativeVSync</b> instance. 87 * @since 9 88 * @version 1.0 89 */ 90 void OH_NativeVSync_Destroy(OH_NativeVSync* nativeVsync); 91 92 /** 93 * @brief Creates a <b>NativeVsync</b> instance.\n 94 * A new <b>NativeVsync</b> instance is created each time this function is called. 95 * 96 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 97 * @param windowID Indicates the id of the associated window. 98 * @param name Indicates the vsync connection name. 99 * @param length Indicates the name's length. 100 * @return Returns the pointer to the <b>NativeVsync</b> instance created. 101 * @since 14 102 * @version 1.0 103 */ 104 OH_NativeVSync* OH_NativeVSync_Create_ForAssociatedWindow(uint64_t windowID, const char* name, unsigned int length); 105 /** 106 * @brief Request next vsync with callback. 107 * If you call this interface multiple times in one frame, it will only call the last callback. 108 * 109 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 110 * @param nativeVsync Indicates the pointer to a NativeVsync. 111 * @param callback Indicates the OH_NativeVSync_FrameCallback which will be called when next vsync coming. 112 * @param data Indicates data which will be used in callback. 113 * @return {@link NATIVE_ERROR_OK} 0 - Success. 114 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL or callback is NULL. 115 * {@link NATIVE_ERROR_BINDER_ERROR} 50401000 - ipc send failed. 116 * @since 9 117 * @version 1.0 118 */ 119 int OH_NativeVSync_RequestFrame(OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data); 120 121 /** 122 * @brief Request next vsync with callback. 123 * If this function is called multiple times in one vsync period, all these callbacks and dataset will be called. 124 * 125 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 126 * @param nativeVsync Indicates the pointer to a NativeVsync. 127 * @param callback Indicates the OH_NativeVSync_FrameCallback which will be called when next vsync coming. 128 * @param data Indicates data which will be used in callback. 129 * @return {@link NATIVE_ERROR_OK} 0 - Success. 130 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL or callback is NULL. 131 * {@link NATIVE_ERROR_BINDER_ERROR} 50401000 - ipc send failed. 132 * @since 12 133 * @version 1.0 134 */ 135 int OH_NativeVSync_RequestFrameWithMultiCallback( 136 OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data); 137 138 /** 139 * @brief Obtains the VSync period. 140 * The VSync period is refreshed only when the <b>OH_NativeVSync_FrameCallback</b> callback is received 141 * following a request for a VSync signal via <b>OH_NativeVSync_RequestFrame</b>. 142 * To obtain the VSync period for the first time using this function, 143 * you need to call <b>OH_NativeVSync_RequestFrame</b> to request a VSync signal. 144 * Once the <b>OH_NativeVSync_FrameCallback</b> callback is received, the vsync period can be obtained. 145 * 146 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 147 * @param nativeVsync Indicates the pointer to a NativeVsync. 148 * @param period Indicates the vsync period. 149 * @return Returns int32_t, return value == 0, success, otherwise, failed. 150 * @since 10 151 * @version 1.0 152 */ 153 int OH_NativeVSync_GetPeriod(OH_NativeVSync* nativeVsync, long long* period); 154 155 /** 156 * @brief Enables DVSync to improve the smoothness of self-drawing animations. 157 * DVSync, short for Decoupled VSync, is a frame timing management policy that is decoupled from the hardware's VSync. 158 * DVSync drives the early rendering of upcoming animation frames by sending VSync signals with future timestamps. 159 * These frames are stored in a frame buffer queue. This helps DVSync reduce potential frame drop and therefore 160 * enhances the smoothness of animations. 161 * DVSync requires free self-drawing frame buffers to store these pre-rendered animation frames. 162 * Therefore, you must ensure that at least one free frame buffer is available. Otherwise, do not enable DVSync. 163 * After DVSync is enabled, you must correctly respond to the early VSync signals and request the subsequent VSync 164 * after the animation frame associated with the previous VSync is complete. In addition, the self-drawing frames must 165 * carry timestamps that align with VSync. 166 * After the animation ends, disable DVSync. 167 * Only phones and tablets support DVSync. 168 * On a platform that does not support DVSync or if another application has enabled DVSync, the attempt to enable it 169 * will not take effect, and the application still receives normal VSync signals. 170 * 171 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 172 * @param nativeVsync Indicates the pointer to a NativeVsync. 173 * @param enable Whether to enable DVSync.The value true means to enable DVSync, and false means the opposite. 174 * @return {@link NATIVE_ERROR_OK} 0 - Success. 175 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL. 176 * {@link NATIVE_ERROR_BINDER_ERROR} 50401000 - ipc send failed. 177 * @since 14 178 * @version 1.0 179 */ 180 int OH_NativeVSync_DVSyncSwitch(OH_NativeVSync* nativeVsync, bool enable); 181 182 /** 183 * @brief Set vsync expected frame rate range. 184 * 185 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 186 * @param nativeVsync Indicates the pointer to a NativeVsync. 187 * @param range Indicates the pointer to an expected rate range. 188 * @return {@link NATIVE_ERROR_OK} 0 - Success. 189 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL or range is NULL or Invalid. 190 * @since 20 191 * @version 1.0 192 */ 193 int OH_NativeVSync_SetExpectedFrameRateRange(OH_NativeVSync* nativeVsync, OH_NativeVSync_ExpectedRateRange* range); 194 #ifdef __cplusplus 195 } 196 #endif 197 198 /** @} */ 199 #endif