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 #ifndef NDK_INCLUDE_NATIVE_VSYNC_H_ 17 #define NDK_INCLUDE_NATIVE_VSYNC_H_ 18 19 /** 20 * @addtogroup NativeVsync 21 * @{ 22 * 23 * @brief Provides the native vsync capability. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 26 * @since 9 27 * @version 1.0 28 */ 29 30 /** 31 * @file native_vsync.h 32 * 33 * @brief Defines the functions for obtaining and using a native vsync. 34 * 35 * @library libnative_vsync.so 36 * @since 9 37 * @version 1.0 38 */ 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 Creates a <b>NativeVsync</b> instance.\n 50 * A new <b>NativeVsync</b> instance is created each time this function is called. 51 * 52 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 53 * @param name Indicates the vsync connection name. 54 * @param length Indicates the name's length. 55 * @return Returns the pointer to the <b>NativeVsync</b> instance created. 56 * @since 9 57 * @version 1.0 58 */ 59 OH_NativeVSync* OH_NativeVSync_Create(const char* name, unsigned int length); 60 61 /** 62 * @brief Delete the NativeVsync instance. 63 * 64 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 65 * @param window Indicates the pointer to a <b>NativeVsync</b> instance. 66 * @since 9 67 * @version 1.0 68 */ 69 void OH_NativeVSync_Destroy(OH_NativeVSync* nativeVsync); 70 71 /** 72 * @brief Request next vsync with callback. 73 * If you call this Interface multi times in one frame, it will only call the last callback. 74 * 75 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 76 * @param nativeVsync Indicates the pointer to a NativeVsync. 77 * @param callback Indicates the OH_NativeVSync_FrameCallback which will be called when next vsync coming. 78 * @param data Indicates data which will be used in callback. 79 * @return {@link NATIVE_ERROR_OK} 0 - Success. 80 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL or callback is NULL. 81 * {@link NATIVE_ERROR_BINDER_ERROR} 50401000 - ipc send failed. 82 * @since 9 83 * @version 1.0 84 */ 85 int OH_NativeVSync_RequestFrame(OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data); 86 87 /** 88 * @brief Request next vsync with callback. 89 * If this function is called multiple times in one vsync period, all these callbacks and datas be callbacked. 90 * 91 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 92 * @param nativeVsync Indicates the pointer to a NativeVsync. 93 * @param callback Indicates the OH_NativeVSync_FrameCallback which will be called when next vsync coming. 94 * @param data Indicates data which will be used in callback. 95 * @return {@link NATIVE_ERROR_OK} 0 - Success. 96 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL or callback is NULL. 97 * {@link NATIVE_ERROR_BINDER_ERROR} 50401000 - ipc send failed. 98 * @since 12 99 * @version 1.0 100 */ 101 int OH_NativeVSync_RequestFrameWithMultiCallback( 102 OH_NativeVSync* nativeVsync, OH_NativeVSync_FrameCallback callback, void* data); 103 104 /** 105 * @brief Get vsync period. 106 * 107 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 108 * @param nativeVsync Indicates the pointer to a NativeVsync. 109 * @param period Indicates the vsync period. 110 * @return Returns int32_t, return value == 0, success, otherwise, failed. 111 * @since 10 112 * @version 1.0 113 */ 114 int OH_NativeVSync_GetPeriod(OH_NativeVSync* nativeVsync, long long* period); 115 116 /** 117 * @brief Enables DVSync to improve the smoothness of self-drawing animations. 118 * DVSync, short for Decoupled VSync, is a frame timing management policy that is decoupled from the hardware's VSync. 119 * DVSync drives the early rendering of upcoming animation frames by sending VSync signals with future timestamps. 120 * These frames are stored in a frame buffer queue. This helps DVSync reduce potential frame drop and therefore 121 * enhances the smoothness of animations. 122 * DVSync requires free self-drawing frame buffers to store these pre-rendered animation frames. 123 * Therefore, you must ensure that at least one free frame buffer is available. Otherwise, do not enable DVSync. 124 * After DVSync is enabled, you must correctly respond to the early VSync signals and request the subsequent VSync 125 * after the animation frame associated with the previous VSync is complete. In addition, the self-drawing frames must 126 * carry timestamps that align with VSync. 127 * After the animation ends, disable DVSync. 128 * On a platform that does not support DVSync or if another application has enabled DVSync, the attempt to enable it 129 * will not take effect, and the application still receives normal VSync signals. 130 * 131 * @syscap SystemCapability.Graphic.Graphic2D.NativeVsync 132 * @param nativeVsync Indicates the pointer to a NativeVsync. 133 * @param enable Whether to enable DVSync.The value true means to enable DVSync, and false means the opposite. 134 * @return {@link NATIVE_ERROR_OK} 0 - Success. 135 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - the parameter nativeVsync is NULL. 136 * {@link NATIVE_ERROR_BINDER_ERROR} 50401000 - ipc send failed. 137 * @since 14 138 * @version 1.0 139 */ 140 int OH_NativeVSync_DVSyncSwitch(OH_NativeVSync* nativeVsync, bool enable); 141 #ifdef __cplusplus 142 } 143 #endif 144 145 #endif