ogl_beamforming

Ultrasound Beamforming Implemented with OpenGL
git clone anongit@rnpnr.xyz:ogl_beamforming.git
Log | Files | Refs | Feed | Submodules | README | LICENSE

ogl_beamformer_lib_base.h (7360B)


      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 	X(INVALID_SIMPLE_PARAMETERS,   18, "invalid simple parameters struct")
     30 
     31 #define X(type, num, string) BF_LIB_ERR_KIND_ ##type = num,
     32 typedef enum {BEAMFORMER_LIB_ERRORS} BeamformerLibErrorKind;
     33 #undef X
     34 
     35 LIB_FN uint32_t beamformer_get_api_version(void);
     36 
     37 LIB_FN BeamformerLibErrorKind beamformer_get_last_error(void);
     38 LIB_FN const char *beamformer_get_last_error_string(void);
     39 LIB_FN const char *beamformer_error_string(BeamformerLibErrorKind kind);
     40 
     41 ///////////////////////////
     42 // NOTE: Simple API
     43 /* Usage:
     44  *   - fill out a BeamformerSimpleParameters
     45  *     - filters need to be created with beamformer_create_filter, and the slot
     46  *       needs to be assigned in compute_stage_parameters
     47  *   - allocate a buffer with enough space for all Float32 or Float32Complex output points
     48  *   - pass the buffer along with the data and parameters to beamformer_beamform_data()
     49  *   - if the function was unsuccessful you can check the error with beamformer_get_last_error()
     50  *     or beamformer_get_last_error_string()
     51  */
     52 LIB_FN uint32_t beamformer_beamform_data(BeamformerSimpleParameters *bp, void *data, uint32_t data_size,
     53                                          void *out_data, int32_t timeout_ms);
     54 
     55 /* NOTE: sets timeout for all functions which may timeout but don't
     56  * take a timeout argument. The majority of such functions will not
     57  * timeout in the normal case and so passing a timeout parameter around
     58  * every where is cumbersome.
     59  *
     60  * timeout_ms: milliseconds in the range [-1, ...) (Default: 0)
     61  *
     62  * IMPORTANT: timeout of -1 will block forever */
     63 LIB_FN uint32_t beamformer_set_global_timeout(int32_t timeout_ms);
     64 
     65 ///////////////////////////
     66 // NOTE: Advanced API
     67 
     68 /* NOTE: downloads the last 32 frames worth of compute timings into output */
     69 LIB_FN uint32_t beamformer_compute_timings(BeamformerComputeStatsTable *output, int32_t timeout_ms);
     70 
     71 /* NOTE: tells the beamformer to start beamforming */
     72 LIB_FN uint32_t beamformer_start_compute(void);
     73 
     74 /* NOTE: waits for previously queued beamform to start or for timeout_ms */
     75 LIB_FN uint32_t beamformer_wait_for_compute_dispatch(int32_t timeout_ms);
     76 
     77 /* NOTE: this function only queue an upload; you must flush (start_compute) */
     78 LIB_FN uint32_t beamformer_push_data(void *data, uint32_t size);
     79 
     80 /* NOTE: pushes data and tries to immediately starts a compute */
     81 LIB_FN uint32_t beamformer_push_data_with_compute(void *data, uint32_t size,
     82                                                   uint32_t image_plane_tag,
     83                                                   uint32_t parameter_slot);
     84 
     85 ///////////////////////////
     86 // Parameter Configuration
     87 LIB_FN uint32_t beamformer_reserve_parameter_blocks(uint32_t count);
     88 LIB_FN uint32_t beamformer_set_pipeline_stage_parameters(uint32_t stage_index, int32_t parameter);
     89 LIB_FN uint32_t beamformer_push_pipeline(int32_t *shaders, uint32_t shader_count, BeamformerDataKind data_kind);
     90 
     91 LIB_FN uint32_t beamformer_set_pipeline_stage_parameters_at(uint32_t stage_index,
     92                                                             int32_t  parameter,
     93                                                             uint32_t parameter_slot);
     94 LIB_FN uint32_t beamformer_push_pipeline_at(int32_t *shaders, uint32_t shader_count,
     95                                             BeamformerDataKind data_kind, uint32_t parameter_slot);
     96 
     97 LIB_FN uint32_t beamformer_push_simple_parameters(BeamformerSimpleParameters *bp);
     98 LIB_FN uint32_t beamformer_push_simple_parameters_at(BeamformerSimpleParameters *bp, uint32_t parameter_slot);
     99 
    100 LIB_FN uint32_t beamformer_push_parameters(BeamformerParameters *);
    101 LIB_FN uint32_t beamformer_push_parameters_ui(BeamformerUIParameters *);
    102 LIB_FN uint32_t beamformer_push_parameters_head(BeamformerParametersHead *);
    103 
    104 LIB_FN uint32_t beamformer_push_parameters_at(BeamformerParameters *, uint32_t parameter_slot);
    105 
    106 LIB_FN uint32_t beamformer_push_channel_mapping(int16_t *mapping, uint32_t count);
    107 LIB_FN uint32_t beamformer_push_channel_mapping_at(int16_t *mapping, uint32_t count, uint32_t parameter_slot);
    108 
    109 LIB_FN uint32_t beamformer_push_sparse_elements(int16_t *elements, uint32_t count);
    110 LIB_FN uint32_t beamformer_push_sparse_elements_at(int16_t *elements, uint32_t count, uint32_t parameter_slot);
    111 
    112 LIB_FN uint32_t beamformer_push_focal_vectors(float *vectors, uint32_t count);
    113 LIB_FN uint32_t beamformer_push_focal_vectors_at(float *vectors, uint32_t count, uint32_t parameter_slot);
    114 
    115 ////////////////////
    116 // Filter Creation
    117 
    118 /* Kaiser Low-Pass Parameter Selection
    119  * see: "Discrete Time Signal Processing" (Oppenheim)
    120  * δ:   fractional passband ripple
    121  * ω_p: highest angular frequency of passband
    122  * ω_s: lowest  angular frequency of stopband
    123  * ω_c: cutoff angular frequency. midpoint of ω_s and ω_p
    124  * M:   length of filter
    125  *
    126  * Define: A = -20log10(δ)
    127  * β:
    128  *   β = 0.1102(A - 8.7)                             if 50 <  A
    129  *   β = 0.5842 * pow(A - 21, 0.4) + 0.07886(A − 21) if 21 <= A <= 50
    130  *   β = 0                                           if       A <  21
    131  * M:
    132  *   M = (A - 8) / (2.285 (ω_s - ω_p))
    133  */
    134 
    135 LIB_FN uint32_t beamformer_create_filter(BeamformerFilterKind kind, float *filter_parameters,
    136                                          uint32_t filter_parameter_count, float sampling_frequency,
    137                                          uint32_t complex, uint8_t filter_slot, uint8_t parameter_block);
    138 
    139 //////////////////////////
    140 // Live Imaging Controls
    141 LIB_FN int32_t  beamformer_live_parameters_get_dirty_flag(void);
    142 LIB_FN uint32_t beamformer_set_live_parameters(BeamformerLiveImagingParameters *);
    143 LIB_FN BeamformerLiveImagingParameters *beamformer_get_live_parameters(void);