beamformer.h (7942B)
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 "OGL 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_reload` with the program's memory and the new library 28 * handle. Once that function has returned it is safe to close the old handle. 29 * 30 * BEAMFORMER_RENDERDOC_HOOKS 31 * Add RenderDoc API calls to capture complete compute frames. As compute is performed 32 * asynchronously from normal rendering it is not possible to capture normally. In this 33 * configuration the beamformer will use the function pointers provided in the 34 * BeamformerInput to make these calls. 35 * IMPORTANT: The renderdoc library will only be visible when the application is started 36 * through RenderDoc. Furthermore the library has startup code which will halt the program 37 * if loaded normally. It must be loaded using platform module loading APIs. For example 38 * GetModuleHandle or dlopen with the RTLD_NOLOAD flag set. 39 * 40 */ 41 42 #ifndef BEAMFORMER_IMPORT 43 #define BEAMFORMER_IMPORT 44 #endif 45 46 #ifndef BEAMFORMER_EXPORT 47 #define BEAMFORMER_EXPORT 48 #endif 49 50 #ifdef BEAMFORMER_DEBUG 51 #undef BEAMFORMER_DEBUG 52 #define BEAMFORMER_DEBUG (1) 53 #else 54 #define BEAMFORMER_DEBUG (0) 55 #endif 56 57 #ifdef BEAMFORMER_RENDERDOC_HOOKS 58 #undef BEAMFORMER_RENDERDOC_HOOKS 59 #define BEAMFORMER_RENDERDOC_HOOKS (1) 60 #else 61 #define BEAMFORMER_RENDERDOC_HOOKS (0) 62 #endif 63 64 /////////////////// 65 // REQUIRED OS API 66 #define OSInvalidHandleValue ((u64)-1) 67 typedef struct { uint64_t value[1]; } OSBarrier; 68 typedef struct { uint64_t value[1]; } OSHandle; 69 typedef struct { uint64_t value[1]; } OSLibrary; 70 typedef struct { uint64_t value[1]; } OSThread; 71 typedef struct { uint64_t value[1]; } OSW32Semaphore; 72 73 typedef uint64_t os_thread_entry_point_fn(void *user_context); 74 75 typedef struct { 76 uint64_t timer_frequency; 77 78 uint32_t logical_processor_count; 79 uint32_t page_size; 80 81 uint8_t path_separator_byte; 82 } OSSystemInfo; 83 84 BEAMFORMER_IMPORT OSSystemInfo * os_system_info(void); 85 86 BEAMFORMER_IMPORT OSThread os_create_thread(const char *name, void *user_context, os_thread_entry_point_fn *fn); 87 BEAMFORMER_IMPORT OSBarrier os_barrier_alloc(uint32_t thread_count); 88 BEAMFORMER_IMPORT void os_barrier_enter(OSBarrier); 89 90 /* NOTE(rnp): since the beamformer may spawn threads, which may need to keep time, 91 * passing in a single timer value with the rest of the input is insufficient. */ 92 BEAMFORMER_IMPORT uint64_t os_timer_count(void); 93 94 BEAMFORMER_IMPORT void os_add_file_watch(const char *path, int64_t path_length, void *user_context); 95 BEAMFORMER_IMPORT int64_t os_read_entire_file(const char *file, void *buffer, int64_t buffer_capacity); 96 97 BEAMFORMER_IMPORT void * os_lookup_symbol(OSLibrary library, const char *symbol); 98 99 /* NOTE(rnp): memory watch timed waiting functions. (-1) is an infinite timeout. the beamformer 100 * will use these with the intention of yielding the thread back to the OS. */ 101 BEAMFORMER_IMPORT uint32_t os_wait_on_address(int32_t *lock, int32_t current, uint32_t timeout_ms); 102 BEAMFORMER_IMPORT void os_wake_all_waiters(int32_t *lock); 103 104 // NOTE(rnp): eventually logging will just be done internally 105 BEAMFORMER_IMPORT void os_console_log(uint8_t *data, int64_t length); 106 BEAMFORMER_IMPORT void os_fatal(uint8_t *data, int64_t length); 107 108 /* NOTE(rnp): this functionality is only needed on win32 to provide cross process 109 * synchronization. While posix has equivalent functionality there is no reason to 110 * use it over a value located in shared memory. */ 111 #if defined(_WIN32) 112 BEAMFORMER_IMPORT OSW32Semaphore os_w32_create_semaphore(const char *name, int32_t initial_count, int32_t maximum_count); 113 BEAMFORMER_IMPORT uint32_t os_w32_semaphore_wait(OSW32Semaphore, uint32_t timeout_ms); 114 BEAMFORMER_IMPORT void os_w32_semaphore_release(OSW32Semaphore, int32_t count); 115 #endif 116 117 ////////////////////////////// 118 // BEAMFORMER APPLICATION API 119 120 typedef enum { 121 BeamformerInputEventKind_ButtonPress, 122 BeamformerInputEventKind_ButtonRelease, 123 BeamformerInputEventKind_ExecutableReload, 124 BeamformerInputEventKind_FileEvent, 125 } BeamformerInputEventKind; 126 127 // TODO: not yet used 128 typedef enum { 129 BeamformerButtonID_MouseLeft, 130 BeamformerButtonID_MouseRight, 131 BeamformerButtonID_MouseMiddle, 132 BeamformerButtonID_Count, 133 } BeamformerButtonID; 134 135 typedef struct { 136 BeamformerInputEventKind kind; 137 union { 138 BeamformerButtonID button_id; 139 void * file_watch_user_context; 140 }; 141 } BeamformerInputEvent; 142 143 typedef struct { 144 /* NOTE(rnp): besides vulkan library code the beamformer will not allocate memory on its 145 * own. Recommended minimum size is 16MB. If shared memory is not provided it is recommended 146 * to increase this to at least 1GB to help facilitate loading of external data files (not yet 147 * implemented). */ 148 void * memory; 149 uint64_t memory_size; 150 151 /* NOTE(rnp): beamformer will use this to communicate with external processes. While it 152 * it won't be required in the future it is currently the only way to load data. 153 * Recommended size is 2-4GB. Currently this size will also limit the size of any data 154 * another process wishes to export. The name is required for listing in the UI so that 155 * users of external processes can open the region on their end. */ 156 void * shared_memory; 157 uint64_t shared_memory_size; 158 uint8_t * shared_memory_name; 159 uint32_t shared_memory_name_length; 160 161 float mouse_x; 162 float mouse_y; 163 float last_mouse_x; 164 float last_mouse_y; 165 166 uint32_t event_count; 167 168 BeamformerInputEvent event_queue[256]; 169 170 /* NOTE(rnp): the beamformer is not allowed to dynamically load libraries 171 * itself. Libraries are optional and the beamformer will not use features 172 * from libraries which have not been provided. */ 173 OSLibrary cuda_library_handle; 174 175 #if BEAMFORMER_RENDERDOC_HOOKS 176 void *renderdoc_start_frame_capture; 177 void *renderdoc_end_frame_capture; 178 #endif 179 } BeamformerInput; 180 181 BEAMFORMER_EXPORT void beamformer_init(BeamformerInput *); 182 183 /* NOTE(rnp): while the platform can also decide to terminate the beamformer, 184 * the beamformer itself may indicate that it wants to terminate. If the 185 * beamformer itself decides to terminate it is unnecessary to call 186 * `beamformer_terminate()` but it will act as a NOP if you do. */ 187 BEAMFORMER_EXPORT uint32_t beamformer_should_close(BeamformerInput *); 188 189 /* IMPORTANT(rnp): since the beamformer may be interacting with external hardware 190 * it is critical that the platform calls this when it wishes to terminate the 191 * beamformer. Otherwise the external hardware may be left in a bad state and require 192 * a reboot. The beamformer will not waste time releasing resources unless it was 193 * compiled with BEAMFORMER_DEBUG enabled (useful for address sanitizer). */ 194 BEAMFORMER_EXPORT void beamformer_terminate(BeamformerInput *); 195 196 #if !BEAMFORMER_DEBUG 197 BEAMFORMER_EXPORT void beamformer_frame_step(BeamformerInput *); 198 #endif 199 200 #if BEAMFORMER_DEBUG 201 BEAMFORMER_EXPORT void beamformer_debug_hot_reload(OSLibrary new_library, BeamformerInput *); 202 #endif 203 204 #endif /*BEAMFORMER_H */