GlueGen v2.6.0-rc-20250712
GlueGen, Native Binding Generator for Java™ (public API).
PTS.java
Go to the documentation of this file.
1/**
2 * Copyright 2023-2024 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 */
28package com.jogamp.common.av;
29
30import java.time.format.DateTimeFormatter;
31import java.time.format.DateTimeParseException;
32import java.time.temporal.ChronoField;
33import java.util.concurrent.TimeUnit;
34
35import com.jogamp.common.os.Clock;
36
37/**
38 * Presentation Timestamp (PTS) with added System Clock Reference (SCR) via
39 * {@link #set(long, int)} and its interpolation via {@link #get(long)}, as well as giving raw access via {@link #getLast()}.
40 * <p>
41 * The relative millisecond PTS since start of the presentation stored in integer
42 * covers a time span of 2'147'483'647 ms (see {@link Integer#MAX_VALUE}
43 * or 2'147'483 seconds or 24.855 days.
44 * </p>
45 */
46public final class PTS {
47 /** An external float value getter */
48 public static interface FloatValue {
49 float get();
50 }
51 private final FloatValue speed;
52 /** System Clock Reference (SCR) of last PTS update. */
53 private volatile long scr;
54 /** Last updated PTS value */
55 private volatile int pts;
56
57 /**
58 * Create new instance, initializing pts with {@link TimeFrameI#INVALID_PTS} and system-clock timestamp with zero.
59 * @param speed external {@link FloatValue} getter for playback speed.
60 * @see #set(long, int)
61 */
62 public PTS(final FloatValue speed) {
63 this.speed = speed;
64 this.scr = 0;
65 this.pts = TimeFrameI.INVALID_PTS;
66 }
67 /**
68 * Create new instance.
69 * @param speed external {@link FloatValue} getter for playback speed.
70 * @param scr System Clock Reference (SCR) in milliseconds of taken pts value, i.e. {@link Clock#currentMillis()}.
71 * @param pts the presentation timestamp (PTS) in milliseconds
72 * @see #set(long, int)
73 */
74 public PTS(final FloatValue speed, final long scr, final int pts) {
75 this.speed = speed;
76 set(scr, pts);
77 }
78 /** Copy constructor */
79 public PTS(final PTS other) {
80 this.speed = other.speed;
81 set(other);
82 }
83
84 /** Returns true if {@link #getLast()} is unequal to {@link TimeFrameI#INVALID_PTS}. */
85 public boolean isValid() { return TimeFrameI.INVALID_PTS != pts; }
86
87 /** Returns true if {@link #getLast()} equals to {@link TimeFrameI#END_OF_STREAM_PTS}, indicating end of stream (EOS). */
88 public boolean isEOS() { return TimeFrameI.END_OF_STREAM_PTS == pts; }
89
90 /** Returns the System Clock Reference (SCR) in milliseconds of last PTS update via {@link #set(long, int)}. */
91 public long getSCR() { return scr; }
92 /** Returns {@link #getSCR()} as time string representation via {@link #toTimeStr(long, boolean)}. */
93 public String getSCRTimeStr(final boolean addFractions) {
94 return toTimeStr(getSCR(), addFractions);
95 }
96 /** Returns the last updated PTS value via {@link #set(long, int)} w/o System Clock Reference (SCR) interpolation. */
97 public int getLast() { return pts; }
98 /** Returns {@link #getLast()} as time string representation via {@link #toTimeStr(long, boolean)}. */
99 public String getLastTimeStr(final boolean addFractions) {
100 return toTimeStr(getLast(), addFractions);
101 }
102
103 /** Returns the external playback speed. */
104 public float getSpeed() { return speed.get(); }
105
106 /**
107 * Updates the PTS value with given System Clock Reference (SCR) in milliseconds.
108 * @param scr System Clock Reference (SCR) in milliseconds of taken PTS value, i.e. {@link Clock#currentMillis()}.
109 * @param pts the presentation timestamp (PTS) in milliseconds
110 */
111 public void set(final long scr, final int pts) {
112 this.scr = scr;
113 this.pts = pts;
114 }
115 /** Sets the PTS value, see {@link #set(long, int)}. */
116 public void setPTS(final int pts) { this.pts = pts; }
117 /** Sets the System Clock Reference (SCR) in milliseconds of last PTS update, see {@link #set(long, int)}. */
118 public void setSCR(final long currentMillis) { scr = currentMillis; }
119
120 /**
121 * Updates the PTS value with values from other {@link PTS} instance.
122 * @param other source {@link PTS} values
123 * @see #get(long)
124 */
125 public void set(final PTS other) {
126 this.scr = other.getSCR();
127 this.pts = other.getLast();
128 }
129
130 /**
131 * Returns the {@link #getLast() last updated PTS}, interpolated by {@link #getSCR() System Clock Reference (SCR)} delta to given {@code currentMillis} and playback {@link #getSpeed() speed}.
132 * <pre>
133 * last_pts + (int) ( ( currentMillis - SCR ) * speed + 0.5f )
134 * </pre>
135 * @param currentMillis current system clock in milliseconds, i.e. {@link Clock#currentMillis()}.
136 * @see #set(long, int)
137 */
138 public int get(final long currentMillis) {
139 return pts + (int) ( ( currentMillis - scr ) * speed.get() + 0.5f );
140 }
141 /** Returns {@link #get(long)} passing {@link Clock#currentMillis()}. */
142 public int getCurrent() { return get( Clock.currentMillis() ); }
143
144 /** Returns {@link #get(long)} as time string representation via {@link #toTimeStr(long, boolean)}. */
145 public String getTimeStr(final long currentMillis, final boolean addFractions) {
146 return toTimeStr(get(currentMillis), addFractions);
147 }
148
149 /** Returns {@link #getLast()} - rhs.{@link #getLast()}. */
150 public int diffLast(final PTS rhs) {
151 return this.pts - rhs.getLast();
152 }
153
154 /** Returns {@link #get(long)} - rhs.{@link #get(long)}. */
155 public int diff(final long currentMillis, final PTS rhs) {
156 return get(currentMillis) - rhs.get(currentMillis);
157 }
158
159 @Override
160 public String toString() { return String.valueOf(pts); }
161
162 public String toString(final long currentMillis) { return "last "+pts+" ms, current "+get(currentMillis)+" ms"; }
163
164 /**
165 * Returns a time string representation '[HH:]mm:ss[.SSS]', dropping unused hour quantities and fractions of seconds optionally.
166 * @param millis complete time in milliseconds
167 * @param addFractions toggle for fractions of seconds
168 * @see #toTimeStr(long)
169 */
170 public static String toTimeStr(final long millis, final boolean addFractions) {
171 final long h = TimeUnit.MILLISECONDS.toHours(millis);
172 final long m = TimeUnit.MILLISECONDS.toMinutes(millis);
173 if( addFractions ) {
174 if( 0 < h ) {
175 return String.format("%02d:%02d:%02d.%03d",
176 h,
177 m - TimeUnit.HOURS.toMinutes(h),
178 TimeUnit.MILLISECONDS.toSeconds(millis) - TimeUnit.MINUTES.toSeconds(m),
179 millis%1000);
180 } else {
181 return String.format("%02d:%02d.%03d",
182 m,
183 TimeUnit.MILLISECONDS.toSeconds(millis) - TimeUnit.MINUTES.toSeconds(m),
184 millis%1000);
185 }
186 } else {
187 if( 0 < h ) {
188 return String.format("%02d:%02d:%02d",
189 h,
190 m - TimeUnit.HOURS.toMinutes(h),
191 TimeUnit.MILLISECONDS.toSeconds(millis) - TimeUnit.MINUTES.toSeconds(m));
192 } else {
193 return String.format("%02d:%02d",
194 m,
195 TimeUnit.MILLISECONDS.toSeconds(millis) - TimeUnit.MINUTES.toSeconds(m));
196 }
197 }
198 }
199
200 /**
201 * Returns a full time string representation 'HH:mm:ss.SSS'.
202 * @param millis complete time in milliseconds
203 * @see #toTimeStr(long, boolean)
204 */
205 public static String toTimeStr(final long millis) {
206 final long h = TimeUnit.MILLISECONDS.toHours(millis);
207 final long m = TimeUnit.MILLISECONDS.toMinutes(millis);
208 return String.format("%02d:%02d:%02d.%03d",
209 h,
210 m - TimeUnit.HOURS.toMinutes(h),
211 TimeUnit.MILLISECONDS.toSeconds(millis) - TimeUnit.MINUTES.toSeconds(m),
212 millis%1000);
213 }
214
215 /**
216 * Returns milliseconds from given string representation in '[H[H]:]m[m]:s[s][.S*]'
217 * @param v the timestamp string to parse.
218 * @param throwException if {@code true}, forwards {@link DateTimeParseException} to caller, otherwise return {@code -1}.
219 */
220 public static int toMillis(final String v, final boolean throwException) {
221 try {
222 return Timestamp.parse(v).get(ChronoField.MILLI_OF_DAY);
223 } catch(final DateTimeParseException pe) {
224 if( throwException ) {
225 throw pe;
226 } else {
227 return -1;
228 }
229 }
230 }
231 /** Returns milliseconds from given string representation in '[H[H]:]m[m]:s[s][.S*]' or {@code -1} for parsing error. */
232 public static int toMillis(final String v) { return toMillis(v, false); }
233
234 private static final DateTimeFormatter Timestamp = DateTimeFormatter.ofPattern(
235 "[H:]m:s[.[SSSSSSSSS][SSSSSSSS][SSSSSSS][SSSSSS][SSSSS][SSSS][SSS][SS][S]]");
236}
Presentation Timestamp (PTS) with added System Clock Reference (SCR) via set(long,...
Definition: PTS.java:46
long getSCR()
Returns the System Clock Reference (SCR) in milliseconds of last PTS update via set(long,...
Definition: PTS.java:91
String toString(final long currentMillis)
Definition: PTS.java:162
String getSCRTimeStr(final boolean addFractions)
Returns getSCR() as time string representation via toTimeStr(long, boolean).
Definition: PTS.java:93
static int toMillis(final String v, final boolean throwException)
Returns milliseconds from given string representation in '[H[H]:]m[m]:s[s][.S*]'.
Definition: PTS.java:220
int diff(final long currentMillis, final PTS rhs)
Returns get(long) - rhs.
Definition: PTS.java:155
int get(final long currentMillis)
Returns the last updated PTS, interpolated by System Clock Reference (SCR) delta to given currentMill...
Definition: PTS.java:138
void setPTS(final int pts)
Sets the PTS value, see set(long, int).
Definition: PTS.java:116
boolean isValid()
Returns true if getLast() is unequal to TimeFrameI#INVALID_PTS.
Definition: PTS.java:85
boolean isEOS()
Returns true if getLast() equals to TimeFrameI#END_OF_STREAM_PTS, indicating end of stream (EOS).
Definition: PTS.java:88
String getTimeStr(final long currentMillis, final boolean addFractions)
Returns get(long) as time string representation via toTimeStr(long, boolean).
Definition: PTS.java:145
String getLastTimeStr(final boolean addFractions)
Returns getLast() as time string representation via toTimeStr(long, boolean).
Definition: PTS.java:99
int getCurrent()
Returns get(long) passing Clock#currentMillis().
Definition: PTS.java:142
PTS(final FloatValue speed, final long scr, final int pts)
Create new instance.
Definition: PTS.java:74
PTS(final PTS other)
Copy constructor.
Definition: PTS.java:79
int diffLast(final PTS rhs)
Returns getLast() - rhs.
Definition: PTS.java:150
void setSCR(final long currentMillis)
Sets the System Clock Reference (SCR) in milliseconds of last PTS update, see set(long,...
Definition: PTS.java:118
static int toMillis(final String v)
Returns milliseconds from given string representation in '[H[H]:]m[m]:s[s][.S*]' or -1 for parsing er...
Definition: PTS.java:232
PTS(final FloatValue speed)
Create new instance, initializing pts with TimeFrameI#INVALID_PTS and system-clock timestamp with zer...
Definition: PTS.java:62
float getSpeed()
Returns the external playback speed.
Definition: PTS.java:104
static String toTimeStr(final long millis, final boolean addFractions)
Returns a time string representation '[HH:]mm:ss[.SSS]', dropping unused hour quantities and fraction...
Definition: PTS.java:170
int getLast()
Returns the last updated PTS value via set(long, int) w/o System Clock Reference (SCR) interpolation.
Definition: PTS.java:97
static String toTimeStr(final long millis)
Returns a full time string representation 'HH:mm:ss.SSS'.
Definition: PTS.java:205
Integer time frame in milliseconds, maybe specialized for texture/video, audio, .
Definition: TimeFrameI.java:49
static final int INVALID_PTS
Constant marking an invalid PTS, i.e.
Definition: TimeFrameI.java:51
static native long currentMillis()
Returns current monotonic milliseconds since start of this application.
An external float value getter.
Definition: PTS.java:48