Gamp v0.0.7-36-g24b1eb6
Gamp: Graphics, Audio, Multimedia and Processing
Loading...
Searching...
No Matches
Gamp.hpp
Go to the documentation of this file.
1/*
2 * Author: Sven Gothel <sgothel@jausoft.com>
3 * Copyright Gothel Software e.K.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * This Source Code Form is subject to the terms of the MIT License
8 * If a copy of the MIT was not distributed with this file,
9 * you can obtain one at https://opensource.org/license/mit/.
10 */
11
12#ifndef JAU_GAMP_HPP_
13#define JAU_GAMP_HPP_
14
15#include <gamp/GampTypes.hpp>
16#include <gamp/Version.hpp>
17
21#include <gamp/wt/Window.hpp>
22
23/**
24 * Gamp: Graphics, Audio, Multimedia and Processing Framework (Native C++, WebAssembly, ...)
25 *
26 * *Gamp* addresses native hardware accelerated graphics, audio, multimedia and processing.
27 * It is implemented in C++, supports WebAssembly and perhaps interfacing w/ other languages/systems.
28 */
29namespace gamp {
30 /** @defgroup Gamp Gamp Root
31 * Graphics, Audio, Multimedia and Processing Framework
32 *
33 * @{
34 */
35
36 std::string lookup_and_register_asset_dir(const char* exe_path, const char* asset_file="fonts/freefont/FreeSansBold.ttf", const char* asset_install_subdir="gamp") noexcept;
37 std::string asset_dir() noexcept;
38 std::string resolve_asset(const std::string &asset_file, bool lookup_direct=false) noexcept;
39 //
40 // gfx toolkit dependent API
41 //
42
43 /** Returns the elapsed monotonic time since `init_gfx_subsystem`, synchronized with the gfx subsystem timer. */
45
46 /** Monitor frames per seconds */
47 int monitor_fps() noexcept;
48
49 /**
50 * Returns optional forced frames per seconds or -1 if unset, set via set_gpu_forced_fps().
51 * Passed to swap_gpu_buffer() by default.
52 */
53 int gpu_forced_fps() noexcept;
54
55 /** Optional forced frames per seconds, pass to swap_gpu_buffer() by default. */
56 void set_gpu_forced_fps(int fps) noexcept;
57
58 /** Returns expected fps, either gpu_forced_fps() if set, otherwise monitor_fps(). */
59 inline int expected_fps() noexcept { int v=gpu_forced_fps(); return v>0?v:monitor_fps(); }
60 /** Returns the expected frame duration in [s], i.e. 1/expected_fps() */
62 return jau::fraction_timespec(1.0/double(expected_fps()));
63 }
64
65 bool is_gfx_subsystem_initialized() noexcept;
66 /** GFX Toolkit: Initialize the subsystem once. */
67 bool init_gfx_subsystem(const char* exe_path);
68 /**
69 * GFX Toolkit: Swap GPU back to front framebuffer of all windows using given fps, maintaining vertical monitor synchronization if possible. fps <= 0 implies automatic fps.
70 *
71 * Should not be called by user, instead use mainloop_default().
72 *
73 * @param fps use gpu_forced_fps()
74 *
75 * @see mainloop_default()
76 */
77 void swap_gpu_buffer(int fps) noexcept;
78
79 /** Returns the measured gpu fps each 5s, starting with monitor_fps() */
80 float gpu_avg_fps() noexcept;
81 /** Returns the measured gpu frame duration in [s] each 5s, starting with 1/gpu_avg_fps() */
82 const jau::fraction_timespec& gpu_avg_framedur() noexcept;
83
84 /**
85 * Performs the whole tasks for all created gamp::wt::Window instances
86 * - handle events and propagates them to registered listener at each window
87 * - renders all gamp::wt::Window first
88 * - calling each gamp::wt::Window::display() method, serving gamp::wt::RenderListener
89 * - swaps front/back buffer of all gamp::wt::Window instances
90 * - adjust timers for whole set
91 *
92 * @return true signaling continuation, false to end the mainloop
93 * @see swap_gpu_buffer()
94 */
95 bool mainloop_default() noexcept;
96
97 /// Calls mainloop_default(), but exits application if returning false
98 void mainloop_void() noexcept;
99
100 void shutdown() noexcept;
101
102 //
103 // input
104 //
105
106 /**
107 * GFX Toolkit: Handle windowing and keyboard events.
108 *
109 * Should be called until function returns false
110 * to process all buffered events.
111 *
112 * @return number of events received
113 */
114 size_t handle_events() noexcept;
115
116 /**
117 * Singleton runtime environment properties
118 *
119 * Also see {@link jau::environment::getExplodingProperties(const std::string & prefixDomain)}.
120 *
121 * Note that all environment variables listed below can be set using `_` instead of `.`.
122 */
123 class GampEnv : public jau::root_environment {
124 friend class BTManager;
125
126 private:
127 GampEnv() noexcept; // NOLINT(modernize-use-equals-delete)
128
129 public:
130 /** Global Debug flag, retrieved first to triggers GampEnv initialization. */
131 const bool DEBUG_GLOBAL;
132
133 private:
134 const bool exploding; // just to trigger exploding properties
135
136 public:
137 /**
138 * Debug all WT event communication
139 *
140 * Environment variable is 'gamp.debug.wt.event'.
141 *
142 */
143 const bool DEBUG_WT_EVENT;
144
145 /**
146 * Debug shader code, i.e. ShaderCode
147 *
148 * Environment variable is 'gamp.debug.render.gl.glsl.code'.
149 *
150 */
152
153 /**
154 * Debug shader state, i.e. ShaderState
155 *
156 * Environment variable is 'gamp.debug.render.gl.glsl.state'.
157 *
158 */
160
161 /**
162 * Debug Graph Renderer
163 *
164 * Environment variable is 'gamp.debug.graph.render'.
165 *
166 */
168
169 public:
170 static GampEnv& get() noexcept {
171 static GampEnv e;
172 return e;
173 }
174 };
175
176
177 /**@}*/
178} // namespace gamp
179
180/** \example RedSquareES2.cpp
181 * This C++ example stub showcases the simple Launcher01.hpp mainloop framework integration. It creates a window, provides
182 * keyboard interaction and uses RedSquareES2 gamp::wt::RenderListener for rendering.
183 */
184
185/** \example RedSquareES2.hpp
186 * This C++ demo showcases a simple gamp::wt::RenderListener, implementing rendering using
187 * gamp::render::gl::glsl::ShaderState setup with attributes, uniforms and gamp::render::gl::glsl::ShaderCode.
188 */
189
190/** \example GearsES2.cpp
191 * This C++ example uses the simple Launcher01.hpp mainloop framework integration. It creates a window, provides
192 * keyboard and pointer interaction including picking, rotate & drag. It
193 * uses GearsES2 gamp::wt::RenderListener for rendering and uses per-pixel-lighting.
194 */
195
196/** \example GearsES2.hpp
197 * This C++ demo showcases a simple gamp::wt::RenderListener exposing three shapes, implementing rendering using
198 * gamp::render::gl::glsl::ShaderState setup with attributes, uniforms and gamp::render::gl::glsl::ShaderCode.
199 */
200
201/** \example Primitives02.cpp
202 * This C++ example demonstrates simple polylines using the the GLU tesselator and per-pixel-lighting.
203 */
204
205/** \example GraphShapes01.cpp
206 * This is the first C++ example demonstrating Graph resolution independent GPU curve rendering.
207 * Multiple complex shapes are rotated with front- and back-face as well as per-pixel-lighting.
208 */
209
210#endif /* JAU_GAMP_HPP_ */
const bool DEBUG_WT_EVENT
Debug all WT event communication.
Definition Gamp.hpp:143
static GampEnv & get() noexcept
Definition Gamp.hpp:170
const bool DEBUG_RENDER_GL_GLSL_CODE
Debug shader code, i.e.
Definition Gamp.hpp:151
const bool DEBUG_GLOBAL
Global Debug flag, retrieved first to triggers GampEnv initialization.
Definition Gamp.hpp:131
friend class BTManager
Definition Gamp.hpp:124
const bool DEBUG_GRAPH_RENDER
Debug Graph Renderer.
Definition Gamp.hpp:167
const bool DEBUG_RENDER_GL_GLSL_STATE
Debug shader state, i.e.
Definition Gamp.hpp:159
int expected_fps() noexcept
Returns expected fps, either gpu_forced_fps() if set, otherwise monitor_fps().
Definition Gamp.hpp:59
std::string lookup_and_register_asset_dir(const char *exe_path, const char *asset_file="fonts/freefont/FreeSansBold.ttf", const char *asset_install_subdir="gamp") noexcept
Definition gamp.cpp:31
const jau::fraction_timespec & gpu_avg_framedur() noexcept
Returns the measured gpu frame duration in [s] each 5s, starting with 1/gpu_avg_fps()
void mainloop_void() noexcept
Calls mainloop_default(), but exits application if returning false.
jau::fraction_timespec getElapsedMonotonicTime() noexcept
Returns the elapsed monotonic time since init_gfx_subsystem, synchronized with the gfx subsystem time...
bool init_gfx_subsystem(const char *exe_path)
GFX Toolkit: Initialize the subsystem once.
std::string resolve_asset(const std::string &asset_file, bool lookup_direct=false) noexcept
Definition gamp.cpp:37
float gpu_avg_fps() noexcept
Returns the measured gpu fps each 5s, starting with monitor_fps()
bool is_gfx_subsystem_initialized() noexcept
jau::fraction_timespec expected_framedur() noexcept
Returns the expected frame duration in [s], i.e.
Definition Gamp.hpp:61
bool mainloop_default() noexcept
Performs the whole tasks for all created gamp::wt::Window instances.
int gpu_forced_fps() noexcept
Returns optional forced frames per seconds or -1 if unset, set via set_gpu_forced_fps().
Definition gamp_sdl2.cpp:84
size_t handle_events() noexcept
GFX Toolkit: Handle windowing and keyboard events.
void swap_gpu_buffer(int fps) noexcept
GFX Toolkit: Swap GPU back to front framebuffer of all windows using given fps, maintaining vertical ...
int monitor_fps() noexcept
Monitor frames per seconds.
Definition gamp_sdl2.cpp:82
void set_gpu_forced_fps(int fps) noexcept
Optional forced frames per seconds, pass to swap_gpu_buffer() by default.
Definition gamp_sdl2.cpp:86
std::string asset_dir() noexcept
Definition gamp.cpp:35
void shutdown() noexcept
Gamp: Graphics, Audio, Multimedia and Processing Framework (Native C++, WebAssembly,...
Definition Gamp.hpp:29
__pack(...): Produces MSVC, clang and gcc compatible lead-in and -out macros.
Definition backtrace.hpp:32
Timespec structure using int64_t for its components in analogy to struct timespec_t on 64-bit platfor...