ogl_beamformer_lib_base.h (9818B)
1 /* See LICENSE for license details. */ 2 #ifndef BEAMFORMER_LIB_EXPORT 3 #if defined(_WIN32) 4 #define BEAMFORMER_LIB_EXPORT __declspec(dllexport) 5 #else 6 #define BEAMFORMER_LIB_EXPORT 7 #endif 8 #endif 9 10 #define BEAMFORMER_LIB_ERRORS \ 11 X(None, 0, "None") \ 12 X(VersionMismatch, 1, "host-library version mismatch") \ 13 X(InvalidAccess, 2, "library in invalid state") \ 14 X(ParameterBlockOverflow, 3, "parameter block count overflow") \ 15 X(ParameterBlockUnallocated, 4, "push to unallocated parameter block") \ 16 X(ComputeStageOverflow, 5, "compute stage overflow") \ 17 X(InvalidComputeStage, 6, "invalid compute shader stage") \ 18 X(InvalidStartShader, 7, "starting shader not Decode or Demodulate") \ 19 X(InvalidDemodulationDataKind, 8, "data kind for demodulation not Int16 or Float") \ 20 X(InvalidImagePlane, 9, "invalid image plane") \ 21 X(InvalidFilterKind, 10, "invalid filter kind") \ 22 X(InvalidDataKind, 11, "invalid data kind") \ 23 X(InvalidContrastMode, 12, "invalid contrast mode") \ 24 X(BufferOverflow, 13, "passed buffer size exceeds available space") \ 25 X(DataSizeMismatch, 14, "data size doesn't match the size specified in parameters") \ 26 X(WorkQueueFull, 15, "work queue full") \ 27 X(ExportSpaceOverflow, 16, "not enough space for data export") \ 28 X(SharedMemory, 17, "failed to open shared memory region") \ 29 X(SyncVariable, 18, "failed to acquire lock within timeout period") \ 30 X(FrameSizeOverflow, 19, "maximum frame size exceeded") \ 31 X(RFDataSizeOverflow, 20, "raw rf size exceeds available GPU space") \ 32 33 #define X(type, num, string) BeamformerLibErrorKind_##type = num, 34 typedef enum {BEAMFORMER_LIB_ERRORS} BeamformerLibErrorKind; 35 #undef X 36 37 BEAMFORMER_LIB_EXPORT uint32_t beamformer_get_api_version(void); 38 39 BEAMFORMER_LIB_EXPORT BeamformerLibErrorKind beamformer_get_last_error(void); 40 BEAMFORMER_LIB_EXPORT const char *beamformer_get_last_error_string(void); 41 BEAMFORMER_LIB_EXPORT const char *beamformer_error_string(BeamformerLibErrorKind kind); 42 43 // NOTE: returns the maximum number of frames which may be beamformed with the provided 44 // parameters before old frames are overwritten. 45 // 46 // returns U64_MAX on error. use beamformer_get_last_error() to determine why 47 BEAMFORMER_LIB_EXPORT uint64_t beamformer_maximum_frames_for_parameters(BeamformerParameters *); 48 BEAMFORMER_LIB_EXPORT uint64_t beamformer_maximum_frames_for_simple_parameters(BeamformerSimpleParameters *); 49 50 // NOTE: returns the maximum single rf dataset size that can be uploaded to the beamformer 51 // returns U64_MAX on error. use beamformer_get_last_error() to determine why 52 BEAMFORMER_LIB_EXPORT uint64_t beamformer_maximum_rf_data_size(void); 53 54 /////////////////////////// 55 // NOTE: Simple API 56 /* Usage: 57 * - fill out a BeamformerSimpleParameters 58 * - filters need to be created with beamformer_create_filter, and the slot 59 * needs to be assigned in compute_stage_parameters 60 * - (Optional) allocate a buffer with enough space for all Float32 or Float32Complex output points 61 * - pass the data and parameters to beamformer_beamform_data() 62 * - pass 0 for out_data if you do not need the beamformed data returned 63 * - if the function was unsuccessful you can check the error with beamformer_get_last_error() 64 * or beamformer_get_last_error_string() 65 */ 66 BEAMFORMER_LIB_EXPORT uint32_t beamformer_beamform_data(BeamformerSimpleParameters *bp, void *data, 67 uint32_t data_size, void *out_data, 68 int32_t timeout_ms); 69 70 /* NOTE: sets timeout for all functions which may timeout but don't 71 * take a timeout argument. The majority of such functions will not 72 * timeout in the normal case and so passing a timeout parameter around 73 * every where is cumbersome. 74 * 75 * timeout_ms: milliseconds (Default: 0) 76 * 77 * IMPORTANT: timeout of -1 will block forever */ 78 BEAMFORMER_LIB_EXPORT void beamformer_set_global_timeout(uint32_t timeout_ms); 79 80 /////////////////////////// 81 // NOTE: Advanced API 82 83 /* NOTE: pushes data and tries to immediately starts a compute */ 84 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_data_with_compute(void *data, uint32_t size, 85 uint32_t image_plane_tag, 86 uint32_t parameter_slot); 87 88 89 /* Returns the last N beamformed frames, ordered from oldest to newest. 90 * out_data: Preallocated output buffer. 91 * out_data_size: Total output buffer size. 92 * count: Number of frames to return. 93 * 94 * NOTE: 95 * - Individual frame sizes are rounded up to 64 byte alignment prior to export 96 * 97 * - Frame size is not guarenteed to be consistent between frames, 98 * it is the callers responsibility to know the correct dimensions of each frame. 99 * 100 * - The buffer will be filled one frame at a time from oldest to newest, 101 * if the output buffer is too small the most recent frames will be dropped. 102 */ 103 BEAMFORMER_LIB_EXPORT uint32_t beamformer_get_last_frames(void *out_data, uint64_t out_data_size, uint32_t count); 104 105 /////////////////////////// 106 // Parameter Configuration 107 BEAMFORMER_LIB_EXPORT uint32_t beamformer_reserve_parameter_blocks(uint32_t count); 108 BEAMFORMER_LIB_EXPORT uint32_t beamformer_set_pipeline_stage_parameters(uint32_t stage_index, 109 int32_t parameter); 110 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_pipeline(int32_t *shaders, uint32_t shader_count, 111 BeamformerDataKind data_kind); 112 113 BEAMFORMER_LIB_EXPORT uint32_t beamformer_set_pipeline_stage_parameters_at(uint32_t stage_index, 114 int32_t parameter, 115 uint32_t parameter_slot); 116 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_pipeline_at(int32_t *shaders, uint32_t shader_count, 117 BeamformerDataKind data_kind, 118 uint32_t parameter_slot); 119 120 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_simple_parameters(BeamformerSimpleParameters *bp); 121 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_simple_parameters_at(BeamformerSimpleParameters *bp, 122 uint32_t parameter_slot); 123 124 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_parameters(BeamformerParameters *); 125 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_parameters_at(BeamformerParameters *, 126 uint32_t parameter_slot); 127 128 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_channel_mapping(int16_t *mapping, uint32_t count); 129 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_channel_mapping_at(int16_t *mapping, uint32_t count, 130 uint32_t parameter_slot); 131 132 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_sparse_elements(int16_t *elements, uint32_t count); 133 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_sparse_elements_at(int16_t *elements, uint32_t count, 134 uint32_t parameter_slot); 135 136 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_focal_vectors(float *vectors, uint32_t count); 137 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_focal_vectors_at(float *vectors, uint32_t count, 138 uint32_t parameter_slot); 139 140 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_transmit_receive_orientations(uint8_t *values, 141 uint32_t count); 142 BEAMFORMER_LIB_EXPORT uint32_t beamformer_push_transmit_receive_orientations_at(uint8_t *values, 143 uint32_t count, 144 uint32_t parameter_slot); 145 146 //////////////////// 147 // Filter Creation 148 149 /* Kaiser Low-Pass Parameter Selection 150 * see: "Discrete Time Signal Processing" (Oppenheim) 151 * δ: fractional passband ripple 152 * ω_p: highest angular frequency of passband 153 * ω_s: lowest angular frequency of stopband 154 * ω_c: cutoff angular frequency. midpoint of ω_s and ω_p 155 * M: length of filter 156 * 157 * Define: A = -20log10(δ) 158 * β: 159 * β = 0.1102(A - 8.7) if 50 < A 160 * β = 0.5842 * pow(A - 21, 0.4) + 0.07886(A − 21) if 21 <= A <= 50 161 * β = 0 if A < 21 162 * M: 163 * M = (A - 8) / (2.285 (ω_s - ω_p)) 164 */ 165 166 BEAMFORMER_LIB_EXPORT uint32_t beamformer_create_filter(BeamformerFilterParameters *filter, 167 uint8_t filter_slot, uint8_t parameter_block); 168 169 ////////////////////////// 170 // Live Imaging Controls 171 BEAMFORMER_LIB_EXPORT int32_t beamformer_live_parameters_get_dirty_flag(void); 172 BEAMFORMER_LIB_EXPORT uint32_t beamformer_set_live_parameters(BeamformerLiveImagingParameters *); 173 BEAMFORMER_LIB_EXPORT BeamformerLiveImagingParameters *beamformer_get_live_parameters(void);