1 /**
2  * Copyright 2011 JogAmp Community. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without modification, are
5  * permitted provided that the following conditions are met:
6  *
7  *    1. Redistributions of source code must retain the above copyright notice, this list of
8  *       conditions and the following disclaimer.
9  *
10  *    2. Redistributions in binary form must reproduce the above copyright notice, this list
11  *       of conditions and the following disclaimer in the documentation and/or other materials
12  *       provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23  *
24  * The views and conclusions contained in the software and documentation are those of the
25  * authors and should not be interpreted as representing official policies, either expressed
26  * or implied, of JogAmp Community.
27  */
28 package com.jogamp.opengl;
29 
30 import java.io.PrintStream;
31 
32 /**
33  * FPSCounter feature.<br>
34  * An implementation initially has the FPSCounter feature disabled.<br>
35  * Use {@link #setUpdateFPSFrames(int, PrintStream)} to enable and disable the FPSCounter feature.
36  */
37 public interface FPSCounter {
38     public static final int DEFAULT_FRAMES_PER_INTERVAL = 5*60;
39 
40     /**
41      * @param frames Update interval in frames.<br> At every rendered <i>frames</i> interval the currentTime and fps values are updated.
42      *        If the <i>frames</i> interval is <= 0, no update will be issued, ie the FPSCounter feature is turned off. You may choose {@link #DEFAULT_FRAMES_PER_INTERVAL}.
43      * @param out optional print stream where the fps values gets printed if not null at every <i>frames</i> interval
44      */
setUpdateFPSFrames(int frames, PrintStream out)45     void setUpdateFPSFrames(int frames, PrintStream out);
46 
47     /**
48      * Reset all performance counter (startTime, currentTime, frame number)
49      */
resetFPSCounter()50     void resetFPSCounter();
51 
52     /**
53      * @return update interval in frames
54      *
55      * @see #setUpdateFPSFrames(int, PrintStream)
56      */
getUpdateFPSFrames()57     int getUpdateFPSFrames();
58 
59     /**
60      * Returns the time of the first display call in milliseconds after enabling this feature via {@link #setUpdateFPSFrames(int, PrintStream)}.<br>
61      * This value is reset via {@link #resetFPSCounter()}.
62      *
63      * @see #setUpdateFPSFrames(int, PrintStream)
64      * @see #resetFPSCounter()
65      */
getFPSStartTime()66     long getFPSStartTime();
67 
68     /**
69      * Returns the time of the last update interval in milliseconds, if this feature is enabled via {@link #setUpdateFPSFrames(int, PrintStream)}.<br>
70      * This value is reset via {@link #resetFPSCounter()}.
71      *
72      * @see #setUpdateFPSFrames(int, PrintStream)
73      * @see #resetFPSCounter()
74      */
getLastFPSUpdateTime()75     long getLastFPSUpdateTime();
76 
77     /**
78      * @return Duration of the last update interval in milliseconds.
79      *
80      * @see #setUpdateFPSFrames(int, PrintStream)
81      * @see #resetFPSCounter()
82      */
getLastFPSPeriod()83     long getLastFPSPeriod();
84 
85     /**
86      * @return Last update interval's frames per seconds, {@link #getUpdateFPSFrames()} / {@link #getLastFPSPeriod()}
87      *
88      * @see #setUpdateFPSFrames(int, PrintStream)
89      * @see #resetFPSCounter()
90      */
getLastFPS()91     float getLastFPS();
92 
93     /**
94      * @return Number of frame rendered since {@link #getFPSStartTime()} up to {@link #getLastFPSUpdateTime()}
95      *
96      * @see #setUpdateFPSFrames(int, PrintStream)
97      * @see #resetFPSCounter()
98      */
getTotalFPSFrames()99     int getTotalFPSFrames();
100 
101     /**
102      * @return Total duration in milliseconds, {@link #getLastFPSUpdateTime()} - {@link #getFPSStartTime()}
103      *
104      * @see #setUpdateFPSFrames(int, PrintStream)
105      * @see #resetFPSCounter()
106      */
getTotalFPSDuration()107     long getTotalFPSDuration();
108 
109 
110     /**
111      * @return Total frames per seconds, {@link #getTotalFPSFrames()} / {@link #getTotalFPSDuration()}
112      *
113      * @see #setUpdateFPSFrames(int, PrintStream)
114      * @see #resetFPSCounter()
115      */
getTotalFPS()116     float getTotalFPS();
117 }
118