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