1 /* 2 * Copyright 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <stdint.h> 20 #include <EGL/egl.h> 21 #include <EGL/eglext.h> 22 #include <jni.h> 23 24 #define MAX_FRAME_BUCKETS 6 25 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 // If an app wishes to use the Android choreographer to provide ticks to Swappy, it can 32 // call the function below. 33 // This function *must* be called before the first Swappy_swap() call. 34 // Afterwards, call this function every choreographer tick. 35 void Swappy_onChoreographer(int64_t frameTimeNanos); 36 37 // Pass callbacks to be called each frame to trace execution 38 struct SwappyTracer { 39 void (*preWait)(void*); 40 void (*postWait)(void*); 41 void (*preSwapBuffers)(void*); 42 void (*postSwapBuffers)(void*, long desiredPresentationTimeMillis); 43 void (*startFrame)(void*, int currentFrame, long currentFrameTimeStampMillis); 44 void* userData; 45 void (*swapIntervalChanged)(void*); 46 47 }; 48 void Swappy_injectTracer(const SwappyTracer *t); 49 50 // Toggle auto-swap interval detection on/off 51 // By default, Swappy will adjust the swap interval based on actual frame rendering time. 52 // If an app wants to override the swap interval calculated by Swappy, it can call 53 // Swappy_setSwapIntervalNS. This will temporarily override Swappy's frame timings but, unless 54 // Swappy_setAutoSwapInterval(false) is called, the timings will continue to be be updated 55 // dynamically, so the swap interval may change. 56 void Swappy_setAutoSwapInterval(bool enabled); 57 58 // Toggle auto-pipeline mode on/off 59 // By default, if auto-swap interval is on, auto-pipelining is on and Swappy will try to reduce 60 // latency by scheduling cpu and gpu work in the same pipeline stage, if it fits. 61 void Swappy_setAutoPipelineMode(bool enabled); 62 63 // Toggle statistics collection on/off 64 // By default, stats collection is off and there is no overhead related to stats. 65 // An app can turn on stats collection by calling Swappy_setStatsMode(true). 66 // Then, the app is expected to call Swappy_recordFrameStart for each frame before starting to 67 // do any CPU related work. 68 // Stats will be logged to logcat with a 'FrameStatistics' tag. 69 // An app can get the stats by calling Swappy_getStats. 70 void Swappy_enableStats(bool enabled); 71 72 struct Swappy_Stats { 73 // total frames swapped by swappy 74 uint64_t totalFrames; 75 76 // Histogram of the number of screen refreshes a frame waited in the compositor queue after 77 // rendering was completed. 78 // for example: 79 // if a frame waited 2 refresh periods in the compositor queue after rendering was done, 80 // the frame will be counted in idleFrames[2] 81 uint64_t idleFrames[MAX_FRAME_BUCKETS]; 82 83 // Histogram of the number of screen refreshes passed between the requested presentation time 84 // and the actual present time. 85 // for example: 86 // if a frame was presented 2 refresh periods after the requested timestamp swappy set, 87 // the frame will be counted in lateFrames[2] 88 uint64_t lateFrames[MAX_FRAME_BUCKETS]; 89 90 // Histogram of the number of screen refreshes passed between two consecutive frames 91 // for example: 92 // if frame N was presented 2 refresh periods after frame N-1 93 // frame N will be counted in offsetFromPreviousFrame[2] 94 uint64_t offsetFromPreviousFrame[MAX_FRAME_BUCKETS]; 95 96 // Histogram of the number of screen refreshes passed between the call to 97 // Swappy_recordFrameStart and the actual present time. 98 // if a frame was presented 2 refresh periods after the call to Swappy_recordFrameStart 99 // the frame will be counted in latencyFrames[2] 100 uint64_t latencyFrames[MAX_FRAME_BUCKETS]; 101 }; 102 103 void Swappy_recordFrameStart(EGLDisplay display, EGLSurface surface); 104 105 void Swappy_getStats(Swappy_Stats *); 106 107 #ifdef __cplusplus 108 }; 109 #endif 110