beamformer.h (12072B)
1 /* See LICENSE for license details. */ 2 #ifndef BEAMFORMER_H 3 #define BEAMFORMER_H 4 5 #include <stdint.h> 6 7 #define BEAMFORMER_NAME_STRING "VK Beamformer" 8 9 /////////////////////////////// 10 // COMPILE TIME CONFIGURATION 11 12 /* NOTE(rnp): By design the beamformer has very little compile time configuration. 13 * The few options it does have are documented here. 14 * 15 * BEAMFORMER_IMPORT 16 * BEAMFORMER_EXPORT 17 * The symbol markup for imported and exported symbols. In a typical 18 * release unity build these are both defined to `static`. 19 * 20 * BEAMFORMER_DEBUG 21 * Compile the beamformer with handling for hot reloading at runtime. 22 * This requires compiling `beamformer_core.c` as a dynamic library which the 23 * platform is required to load at runtime. 24 * IMPORTANT: When the platform wants to reload the library at runtime it 25 * MUST NOT unload the old library immediately; the beamformer may still 26 * be executing code in old library. Instead the platform must first call 27 * `beamformer_debug_hot_release` with the program's memory, then it may close the 28 * old handle. Then `beamformer_debug_hot_reload` should be called with the new handle 29 * so that the beamformer may resume operation. 30 * 31 * BEAMFORMER_RENDERDOC_HOOKS 32 * Add RenderDoc API calls to capture complete compute frames. As compute is performed 33 * asynchronously from normal rendering it is not possible to capture normally. In this 34 * configuration the beamformer will use the function pointers provided in the 35 * BeamformerInput to make these calls. 36 * IMPORTANT: The renderdoc library will only be visible when the application is started 37 * through RenderDoc. Furthermore the library has startup code which will halt the program 38 * if loaded normally. It must be loaded using platform module loading APIs. For example 39 * GetModuleHandle or dlopen with the RTLD_NOLOAD flag set. 40 * 41 */ 42 43 #ifndef BEAMFORMER_IMPORT 44 #define BEAMFORMER_IMPORT 45 #endif 46 47 #ifndef BEAMFORMER_EXPORT 48 #define BEAMFORMER_EXPORT 49 #endif 50 51 #ifdef BEAMFORMER_DEBUG 52 #undef BEAMFORMER_DEBUG 53 #define BEAMFORMER_DEBUG (1) 54 #else 55 #define BEAMFORMER_DEBUG (0) 56 #endif 57 58 #ifdef BEAMFORMER_RENDERDOC_HOOKS 59 #undef BEAMFORMER_RENDERDOC_HOOKS 60 #define BEAMFORMER_RENDERDOC_HOOKS (1) 61 #else 62 #define BEAMFORMER_RENDERDOC_HOOKS (0) 63 #endif 64 65 /////////////////// 66 // REQUIRED OS API 67 // 68 // NOTE(rnp): in addition to the platform layer defined in base_platform.h 69 // the beamformer additionally requires the following functions. 70 71 BEAMFORMER_IMPORT void os_add_file_watch(const char *path, int64_t path_length, void *user_context); 72 73 BEAMFORMER_IMPORT void * os_lookup_symbol(OSLibrary library, const char *symbol); 74 75 // NOTE(rnp): currently beamformer will only create one window. 76 // once raylib is removed it may request multiple 77 BEAMFORMER_IMPORT OSWindow os_window_create(uint8_t *title, int64_t title_length, int32_t width, int32_t height); 78 //BEAMFORMER_IMPORT void os_window_title(OSWindow window, uint8_t *title, int64_t title_length); 79 //BEAMFORMER_IMPORT void os_window_destroy(OSWindow window); 80 81 BEAMFORMER_IMPORT uint8_t * os_get_clipboard_text(int64_t *length); 82 BEAMFORMER_IMPORT void os_set_clipboard_text(uint8_t *data, int64_t length); 83 84 // NOTE(rnp): eventually logging will just be done internally 85 BEAMFORMER_IMPORT void os_console_log(uint8_t *data, int64_t length); 86 BEAMFORMER_IMPORT void os_fatal(uint8_t *data, int64_t length); 87 88 // NOTE(rnp): for vulkan cross API export on win32 (will be removed eventually) 89 BEAMFORMER_IMPORT void os_release_handle(OSHandle handle); 90 91 ////////////////////////////// 92 // BEAMFORMER APPLICATION API 93 94 typedef enum { 95 BeamformerInputEventKind_ButtonPress, 96 BeamformerInputEventKind_ButtonRelease, 97 BeamformerInputEventKind_MouseScroll, 98 BeamformerInputEventKind_WindowResize, 99 BeamformerInputEventKind_ExecutableReload, 100 BeamformerInputEventKind_FileEvent, 101 } BeamformerInputEventKind; 102 103 typedef enum { 104 BeamformerButtonID_Space = ' ', 105 BeamformerButtonID_Apostrophe = '\'', 106 BeamformerButtonID_Comma = ',', 107 BeamformerButtonID_Minus = '-', 108 BeamformerButtonID_Period = '.', 109 BeamformerButtonID_Slash = '/', 110 BeamformerButtonID_0 = '0', 111 BeamformerButtonID_1 = '1', 112 BeamformerButtonID_2 = '2', 113 BeamformerButtonID_3 = '3', 114 BeamformerButtonID_4 = '4', 115 BeamformerButtonID_5 = '5', 116 BeamformerButtonID_6 = '6', 117 BeamformerButtonID_7 = '7', 118 BeamformerButtonID_8 = '8', 119 BeamformerButtonID_9 = '9', 120 BeamformerButtonID_Semicolon = ';', 121 BeamformerButtonID_Equal = '=', 122 BeamformerButtonID_A = 'A', 123 BeamformerButtonID_B = 'B', 124 BeamformerButtonID_C = 'C', 125 BeamformerButtonID_D = 'D', 126 BeamformerButtonID_E = 'E', 127 BeamformerButtonID_F = 'F', 128 BeamformerButtonID_G = 'G', 129 BeamformerButtonID_H = 'H', 130 BeamformerButtonID_I = 'I', 131 BeamformerButtonID_J = 'J', 132 BeamformerButtonID_K = 'K', 133 BeamformerButtonID_L = 'L', 134 BeamformerButtonID_M = 'M', 135 BeamformerButtonID_N = 'N', 136 BeamformerButtonID_O = 'O', 137 BeamformerButtonID_P = 'P', 138 BeamformerButtonID_Q = 'Q', 139 BeamformerButtonID_R = 'R', 140 BeamformerButtonID_S = 'S', 141 BeamformerButtonID_T = 'T', 142 BeamformerButtonID_U = 'U', 143 BeamformerButtonID_V = 'V', 144 BeamformerButtonID_W = 'W', 145 BeamformerButtonID_X = 'X', 146 BeamformerButtonID_Y = 'Y', 147 BeamformerButtonID_Z = 'Z', 148 BeamformerButtonID_LeftBracket = '[', 149 BeamformerButtonID_Backslash = '\\', 150 BeamformerButtonID_RightBracket = ']', 151 BeamformerButtonID_Grave = '`', 152 153 BeamformerButtonID_Escape, 154 BeamformerButtonID_Enter, 155 BeamformerButtonID_Tab, 156 BeamformerButtonID_Backspace, 157 BeamformerButtonID_Insert, 158 BeamformerButtonID_Delete, 159 BeamformerButtonID_Right, 160 BeamformerButtonID_Left, 161 BeamformerButtonID_Down, 162 BeamformerButtonID_Up, 163 BeamformerButtonID_PageUp, 164 BeamformerButtonID_PageDown, 165 BeamformerButtonID_Home, 166 BeamformerButtonID_End, 167 BeamformerButtonID_CapsLock, 168 BeamformerButtonID_ScrollLock, 169 BeamformerButtonID_NumLock, 170 BeamformerButtonID_PrintScreen, 171 BeamformerButtonID_Pause, 172 BeamformerButtonID_F1, 173 BeamformerButtonID_F2, 174 BeamformerButtonID_F3, 175 BeamformerButtonID_F4, 176 BeamformerButtonID_F5, 177 BeamformerButtonID_F6, 178 BeamformerButtonID_F7, 179 BeamformerButtonID_F8, 180 BeamformerButtonID_F9, 181 BeamformerButtonID_F10, 182 BeamformerButtonID_F11, 183 BeamformerButtonID_F12, 184 BeamformerButtonID_F13, 185 BeamformerButtonID_F14, 186 BeamformerButtonID_F15, 187 BeamformerButtonID_F16, 188 BeamformerButtonID_F17, 189 BeamformerButtonID_F18, 190 BeamformerButtonID_F19, 191 BeamformerButtonID_F20, 192 BeamformerButtonID_F21, 193 BeamformerButtonID_F22, 194 BeamformerButtonID_F23, 195 BeamformerButtonID_F24, 196 BeamformerButtonID_F25, 197 BeamformerButtonID_KP0, 198 BeamformerButtonID_KP1, 199 BeamformerButtonID_KP2, 200 BeamformerButtonID_KP3, 201 BeamformerButtonID_KP4, 202 BeamformerButtonID_KP5, 203 BeamformerButtonID_KP6, 204 BeamformerButtonID_KP7, 205 BeamformerButtonID_KP8, 206 BeamformerButtonID_KP9, 207 BeamformerButtonID_KPDecimal, 208 BeamformerButtonID_KPDivide, 209 BeamformerButtonID_KPMultiply, 210 BeamformerButtonID_KPSubtract, 211 BeamformerButtonID_KPAdd, 212 BeamformerButtonID_KPEnter, 213 BeamformerButtonID_KPEqual, 214 215 BeamformerButtonID_LeftShift, 216 BeamformerButtonID_LeftControl, 217 BeamformerButtonID_LeftAlt, 218 BeamformerButtonID_LeftSuper, 219 BeamformerButtonID_RightShift, 220 BeamformerButtonID_RightControl, 221 BeamformerButtonID_RightAlt, 222 BeamformerButtonID_RightSuper, 223 BeamformerButtonID_ModifierFirst = BeamformerButtonID_LeftShift, 224 BeamformerButtonID_ModifierLast = BeamformerButtonID_RightSuper, 225 226 BeamformerButtonID_Menu, 227 228 BeamformerButtonID_MouseLeft, 229 BeamformerButtonID_MouseRight, 230 BeamformerButtonID_MouseMiddle, 231 232 BeamformerButtonID_Count, 233 } BeamformerButtonID; 234 235 typedef enum { 236 BeamformerInputModifier_LeftAlt = (1 << 0), 237 BeamformerInputModifier_RightAlt = (1 << 1), 238 239 BeamformerInputModifier_LeftControl = (1 << 2), 240 BeamformerInputModifier_RightControl = (1 << 3), 241 242 BeamformerInputModifier_LeftShift = (1 << 4), 243 BeamformerInputModifier_RightShift = (1 << 5), 244 245 BeamformerInputModifier_LeftMeta = (1 << 6), 246 BeamformerInputModifier_RightMeta = (1 << 7), 247 248 BeamformerInputModifier_Alt = BeamformerInputModifier_LeftAlt|BeamformerInputModifier_RightAlt, 249 BeamformerInputModifier_Control = BeamformerInputModifier_LeftControl|BeamformerInputModifier_RightControl, 250 BeamformerInputModifier_Shift = BeamformerInputModifier_LeftShift|BeamformerInputModifier_RightShift, 251 BeamformerInputModifier_Meta = BeamformerInputModifier_LeftMeta|BeamformerInputModifier_RightMeta, 252 BeamformerInputModifier_Any = BeamformerInputModifier_Alt| 253 BeamformerInputModifier_Control| 254 BeamformerInputModifier_Shift| 255 BeamformerInputModifier_Meta, 256 } BeamformerInputModifiers; 257 258 typedef struct { 259 BeamformerInputEventKind kind; 260 BeamformerInputModifiers modifiers; 261 union { 262 struct { 263 BeamformerButtonID button_id; 264 // NOTE(rnp): if the button is not also an input key codepoint should be 0 265 uint32_t codepoint; 266 }; 267 struct {float x, y;} scroll; 268 269 struct { 270 uint32_t width, height; 271 OSWindow window; 272 } window_resize; 273 274 void *file_watch_user_context; 275 }; 276 } BeamformerInputEvent; 277 278 typedef struct { 279 /* NOTE(rnp): beamformer will use this to communicate with external processes. While it 280 * it won't be required in the future it is currently the only way to load data. 281 * Recommended size is 2-4GB. Currently this size will also limit the size of any data 282 * another process wishes to export. The name is required for listing in the UI so that 283 * users of external processes can open the region on their end. */ 284 void * shared_memory; 285 uint64_t shared_memory_size; 286 uint8_t * shared_memory_name; 287 uint32_t shared_memory_name_length; 288 289 float mouse_x; 290 float mouse_y; 291 292 uint32_t event_count; 293 294 BeamformerInputEvent event_queue[256]; 295 296 /* NOTE(rnp): the beamformer is not allowed to dynamically load libraries 297 * itself. Besides Vulkan, which is required, libraries are optional and 298 * the beamformer will not use features from libraries which have not 299 * been provided. */ 300 OSLibrary cuda_library_handle; 301 OSLibrary vulkan_library_handle; 302 303 #if BEAMFORMER_RENDERDOC_HOOKS 304 void *renderdoc_start_frame_capture; 305 void *renderdoc_end_frame_capture; 306 #endif 307 } BeamformerInput; 308 309 // NOTE(rnp): returns the beamformer's memory, to be passed as part of input. 310 BEAMFORMER_EXPORT void *beamformer_init(BeamformerInput *); 311 312 /* NOTE(rnp): while the platform can also decide to terminate the beamformer, 313 * the beamformer itself may indicate that it wants to terminate. If the 314 * beamformer itself decides to terminate it is unnecessary to call 315 * `beamformer_terminate()` but it will act as a NOP if you do. */ 316 BEAMFORMER_EXPORT uint32_t beamformer_should_close(void *memory, BeamformerInput *); 317 318 /* IMPORTANT(rnp): since the beamformer may be interacting with external hardware 319 * it is critical that the platform calls this when it wishes to terminate the 320 * beamformer. Otherwise the external hardware may be left in a bad state and require 321 * a reboot. The beamformer will not waste time releasing resources unless it was 322 * compiled with BEAMFORMER_DEBUG enabled (useful for address sanitizer). */ 323 BEAMFORMER_EXPORT void beamformer_terminate(void *memory, BeamformerInput *); 324 325 #if !BEAMFORMER_DEBUG 326 BEAMFORMER_EXPORT void beamformer_frame_step(void *memory, BeamformerInput *); 327 #endif 328 329 #if BEAMFORMER_DEBUG 330 BEAMFORMER_EXPORT void beamformer_debug_hot_release(void *memory, BeamformerInput *); 331 BEAMFORMER_EXPORT void beamformer_debug_hot_reload(OSLibrary new_library); 332 #endif 333 334 #endif /*BEAMFORMER_H */