ogl_beamformer_lib_base.h (6568B)
1 /* See LICENSE for license details. */ 2 #ifndef LIB_FN 3 #if defined(_WIN32) 4 #define LIB_FN __declspec(dllexport) 5 #else 6 #define LIB_FN 7 #endif 8 #endif 9 10 #define BEAMFORMER_LIB_ERRORS \ 11 X(NONE, 0, "None") \ 12 X(VERSION_MISMATCH, 1, "host-library version mismatch") \ 13 X(INVALID_ACCESS, 2, "library in invalid state") \ 14 X(PARAMETER_BLOCK_OVERFLOW, 3, "parameter block count overflow") \ 15 X(PARAMETER_BLOCK_UNALLOCATED, 4, "push to unallocated parameter block") \ 16 X(COMPUTE_STAGE_OVERFLOW, 5, "compute stage overflow") \ 17 X(INVALID_COMPUTE_STAGE, 6, "invalid compute shader stage") \ 18 X(INVALID_START_SHADER, 7, "starting shader not Decode or Demodulate") \ 19 X(INVALID_DEMOD_DATA_KIND, 8, "data kind for demodulation not Int16 or Float") \ 20 X(INVALID_IMAGE_PLANE, 9, "invalid image plane") \ 21 X(BUFFER_OVERFLOW, 10, "passed buffer size exceeds available space") \ 22 X(WORK_QUEUE_FULL, 11, "work queue full") \ 23 X(EXPORT_SPACE_OVERFLOW, 12, "not enough space for data export") \ 24 X(SHARED_MEMORY, 13, "failed to open shared memory region") \ 25 X(SYNC_VARIABLE, 14, "failed to acquire lock within timeout period") \ 26 X(INVALID_TIMEOUT, 15, "invalid timeout value") \ 27 X(INVALID_FILTER_KIND, 16, "invalid filter kind") \ 28 X(INVALID_FILTER_PARAM_COUNT, 17, "invalid parameters count passed for filter") 29 30 #define X(type, num, string) BF_LIB_ERR_KIND_ ##type = num, 31 typedef enum {BEAMFORMER_LIB_ERRORS} BeamformerLibErrorKind; 32 #undef X 33 34 LIB_FN uint32_t beamformer_get_api_version(void); 35 36 LIB_FN BeamformerLibErrorKind beamformer_get_last_error(void); 37 LIB_FN const char *beamformer_get_last_error_string(void); 38 LIB_FN const char *beamformer_error_string(BeamformerLibErrorKind kind); 39 40 /* NOTE: sets timeout for all functions which may timeout but don't 41 * take a timeout argument. The majority of such functions will not 42 * timeout in the normal case and so passing a timeout parameter around 43 * every where is cumbersome. 44 * 45 * timeout_ms: milliseconds in the range [-1, ...) (Default: 0) 46 * 47 * IMPORTANT: timeout of -1 will block forever */ 48 LIB_FN uint32_t beamformer_set_global_timeout(int32_t timeout_ms); 49 50 /* NOTE: sends data and waits for (complex) beamformed data to be returned. 51 * out_data: must be allocated by the caller as 2 floats per output point. */ 52 LIB_FN uint32_t beamform_data_synchronized(void *data, uint32_t data_size, int32_t output_points[3], 53 float *out_data, int32_t timeout_ms); 54 55 /* NOTE: downloads the last 32 frames worth of compute timings into output */ 56 LIB_FN uint32_t beamformer_compute_timings(BeamformerComputeStatsTable *output, int32_t timeout_ms); 57 58 /* NOTE: tells the beamformer to start beamforming */ 59 LIB_FN uint32_t beamformer_start_compute(void); 60 61 LIB_FN uint32_t beamformer_push_data_with_compute(void *data, uint32_t size, 62 uint32_t image_plane_tag, 63 uint32_t parameter_slot); 64 65 /* NOTE: waits for previously queued beamform to start or for timeout_ms */ 66 LIB_FN uint32_t beamformer_wait_for_compute_dispatch(int32_t timeout_ms); 67 68 /* NOTE: these functions only queue an upload; you must flush (start_compute) */ 69 LIB_FN uint32_t beamformer_push_data(void *data, uint32_t size); 70 LIB_FN uint32_t beamformer_push_channel_mapping(int16_t *mapping, uint32_t count); 71 LIB_FN uint32_t beamformer_push_sparse_elements(int16_t *elements, uint32_t count); 72 LIB_FN uint32_t beamformer_push_focal_vectors(float *vectors, uint32_t count); 73 74 /////////////////////////// 75 // Parameter Configuration 76 LIB_FN uint32_t beamformer_reserve_parameter_blocks(uint32_t count); 77 LIB_FN uint32_t beamformer_set_pipeline_stage_parameters(uint32_t stage_index, int32_t parameter); 78 LIB_FN uint32_t beamformer_push_pipeline(int32_t *shaders, uint32_t shader_count, BeamformerDataKind data_kind); 79 LIB_FN uint32_t beamformer_push_parameters(BeamformerParameters *); 80 LIB_FN uint32_t beamformer_push_parameters_ui(BeamformerUIParameters *); 81 LIB_FN uint32_t beamformer_push_parameters_head(BeamformerParametersHead *); 82 83 LIB_FN uint32_t beamformer_set_pipeline_stage_parameters_at(uint32_t stage_index, 84 int32_t parameter, 85 uint32_t parameter_slot); 86 LIB_FN uint32_t beamformer_push_pipeline_at(int32_t *shaders, uint32_t shader_count, 87 BeamformerDataKind data_kind, uint32_t parameter_slot); 88 LIB_FN uint32_t beamformer_push_parameters_at(BeamformerParameters *, uint32_t parameter_slot); 89 90 LIB_FN uint32_t beamformer_push_channel_mapping_at(int16_t *mapping, uint32_t count, uint32_t parameter_slot); 91 LIB_FN uint32_t beamformer_push_sparse_elements_at(int16_t *elements, uint32_t count, uint32_t parameter_slot); 92 LIB_FN uint32_t beamformer_push_focal_vectors_at(float *vectors, uint32_t count, uint32_t parameter_slot); 93 94 //////////////////// 95 // Filter Creation 96 97 /* Kaiser Low-Pass Parameter Selection 98 * see: "Discrete Time Signal Processing" (Oppenheim) 99 * δ: fractional passband ripple 100 * ω_p: highest angular frequency of passband 101 * ω_s: lowest angular frequency of stopband 102 * ω_c: cutoff angular frequency. midpoint of ω_s and ω_p 103 * M: length of filter 104 * 105 * Define: A = -20log10(δ) 106 * β: 107 * β = 0.1102(A - 8.7) if 50 < A 108 * β = 0.5842 * pow(A - 21, 0.4) + 0.07886(A − 21) if 21 <= A <= 50 109 * β = 0 if A < 21 110 * M: 111 * M = (A - 8) / (2.285 (ω_s - ω_p)) 112 */ 113 114 LIB_FN uint32_t beamformer_create_filter(BeamformerFilterKind kind, float *filter_parameters, 115 uint32_t filter_parameter_count, float sampling_frequency, 116 uint32_t complex, uint8_t filter_slot, uint8_t parameter_block); 117 118 ////////////////////////// 119 // Live Imaging Controls 120 LIB_FN int32_t beamformer_live_parameters_get_dirty_flag(void); 121 LIB_FN uint32_t beamformer_set_live_parameters(BeamformerLiveImagingParameters *); 122 LIB_FN BeamformerLiveImagingParameters *beamformer_get_live_parameters(void);