HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
flicks.h
Go to the documentation of this file.
1 /**
2  * Copyright (c) 2017-present, Facebook, Inc.
3  * All rights reserved.
4  *
5  * This source code is licensed under the BSD-style license found in the
6  * LICENSE file in the root directory of this source tree.
7  */
8 
9 #pragma once
10 
11 #include <chrono>
12 #include <cstdint>
13 #include <functional>
14 #include <ratio>
15 
16 namespace util {
17 
18 //! A flick (frame-tick) is a very small unit of time. It is 1/705600000 of a second, exactly.
19 //!
20 //! 1 flick = 1/705600000 second
21 //!
22 //! This unit of time is the smallest time unit which is LARGER than a nanosecond,
23 //! and can in integer quantities exactly represent a single frame duration for
24 //! 24 Hz, 25 Hz, 30 Hz, 48 Hz, 50 Hz, 60 Hz, 90 Hz, 100 Hz, 120 Hz, and also 1/1000 divisions of each,
25 //! as well as a single sample duration for 8 kHz, 16 kHz, 22.05 kHz, 24 kHz, 32 kHz, 44.1 kHz,
26 //! 48 kHz, 88.2 kHz, 96 kHz, and 192kHz, as well as the NTSC frame durations for
27 //! 24 * (1000/1001) Hz, 30 * (1000/1001) Hz, 60 * (1000/1001) Hz, and 120 * (1000/1001) Hz.
28 //!
29 //! That above was one hell of a run-on sentence, but it's strictly and completely correct in its
30 //! description of the unit.
31 //!
32 //! This makes flicks suitable for use via std::chrono::duration and std::ratio for doing timing work
33 //! against the system high resolution clock, which is in nanoseconds, but doesn't get slightly
34 //! out of sync when doing common frame rates.
35 //!
36 //! We also support some common audio sample rates as well. This list is not exhaustive, but covers
37 //! the majority of digital audio formats. They are 8kHz, 16kHz, 22.05kHz, 24kHz, 32kHz, 44.1kHz,
38 //! 48kHz, 88.2kHz, 96kHz, and 192kHz.
39 //!
40 //! Though it is not part of the design criteria, 144 Hz, which some newer monitors refresh at,
41 //! does work correctly with flicks.
42 //!
43 //! NTSC IS NOT EXPLICITLY SUPPORTED IN ALL OF ITS SUBTLE NUANCES, BUT:
44 //! The NTSC variations (~23.976, ~29.97, etc) are approximately defined as 24 * 1000/1001 and
45 //! 30 * 1000/1001, etc. These can be represented exactly in flicks, but 1/1000 divisions are not
46 //! available.
47 //!
48 //! Many folks online have pointed out that NTSC technically has a variable frame rate,
49 //! and that this is handled correctly in other media playback libraries such as QuickTime.
50 //! The goal of flicks is to provide a simple, convenient std::chrono::duration to work
51 //! with when writing code that works with simulation and time in media, but not explicitly to
52 //! handle complex, variable-rate playback scenarios. So we'll stick with the 1000/1001 approximations,
53 //! and leave it at that!
54 //!
55 //! Details
56 //!
57 //! 24 fps frame: 29400000 flicks
58 //! 25 fps frame: 28224000 flicks
59 //! 30 fps frame: 23520000 flicks
60 //! 48 fps frame: 14700000 flicks
61 //! 50 fps frame: 14112000 flicks
62 //! 60 fps frame: 11760000 flicks
63 //! 90 fps frame: 7840000 flicks
64 //! 100 fps frame: 7056000 flicks
65 //! 120 fps frame: 5880000 flicks
66 //! 8000 fps frame: 88200 flicks
67 //! 16000 fps frame: 44100 flicks
68 //! 22050 fps frame: 32000 flicks
69 //! 24000 fps frame: 29400 flicks
70 //! 32000 fps frame: 22050 flicks
71 //! 44100 fps frame: 16000 flicks
72 //! 48000 fps frame: 14700 flicks
73 //! 88200 fps frame: 8000 flicks
74 //! 96000 fps frame: 7350 flicks
75 //! 192000 fps frame: 3675 flicks
76 //!
77 //! NTSC:
78 //!
79 //! 24 * 1000/1001 (~23.976) fps frame: 29429400 flicks
80 //! 30 * 1000/1001 (~29.97) fps frame: 23543520 flicks
81 //! 60 * 1000/1001 (~59.94) fps frame: 11771760 flicks
82 //! 120 * 1000/1001 (~119.88) fps frame: 5885880 flicks
83 
84 using flicks = std::chrono::duration<std::chrono::nanoseconds::rep,
85  std::ratio<1, 705600000>>;
86 
87 //! Useful constants
88 constexpr flicks k_flicks_zero_seconds{
89  std::chrono::duration_cast<flicks>(std::chrono::seconds{0})};
91  std::chrono::duration_cast<flicks>(std::chrono::seconds{1})};
93  std::chrono::duration_cast<flicks>(
94  std::chrono::duration<flicks::rep, std::ratio<1, 24>>{1})};
96  std::chrono::duration_cast<flicks>(
97  std::chrono::duration<flicks::rep, std::ratio<1, 90>>{1})};
99 
100 //! Convert flicks to seconds as doubles
101 //!
102 constexpr double to_seconds(const flicks ns) {
103  return std::chrono::duration_cast<std::chrono::duration<double>>(ns).count();
104 }
105 
106 //! Convert doubles (as seconds) to flicks
107 //!
108 constexpr flicks to_flicks(const double s) {
109  return std::chrono::duration_cast<flicks>(std::chrono::duration<double>{s});
110 }
111 
112 //! Convert a regular duration to flicks
113 //!
114 template <class Rep, class Period>
115 constexpr flicks flicks_cast(
116  const std::chrono::duration<Rep, Period> in_duration) {
117  return std::chrono::duration_cast<flicks>(in_duration);
118 }
119 
120 //! This is a std::hash-esque hash functor
121 //!
122 struct flicks_hash {
124  using result_type = size_t;
126  return std::hash<flicks::rep>{}(s.count());
127  }
128 };
129 
130 } // namespace util
constexpr flicks k_flicks_one_ninetieth_of_second
Definition: flicks.h:95
constexpr flicks flicks_cast(const std::chrono::duration< Rep, Period > in_duration)
Definition: flicks.h:115
result_type operator()(argument_type const &s) const
Definition: flicks.h:125
GLdouble s
Definition: glad.h:3009
ImageBuf OIIO_API min(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
flicks argument_type
Definition: flicks.h:123
constexpr flicks k_flicks_one_twenty_fourth_of_second
Definition: flicks.h:92
size_t result_type
Definition: flicks.h:124
std::chrono::duration< std::chrono::nanoseconds::rep, std::ratio< 1, 705600000 >> flicks
Definition: flicks.h:85
constexpr flicks k_flicks_one_second
Definition: flicks.h:90
constexpr double to_seconds(const flicks ns)
Definition: flicks.h:102
constexpr flicks to_flicks(const double s)
Definition: flicks.h:108
GLint GLsizei count
Definition: glcorearb.h:405
constexpr flicks k_flicks_min_time
Definition: flicks.h:98