From d49754381b1d35cddbbc521aff7db13b31014be4 Mon Sep 17 00:00:00 2001 From: Gregor Weiss Date: Fri, 8 Nov 2024 11:03:59 +0100 Subject: [PATCH] Docstring in libbwc.c and bits of renaming. --- src/library/libbwc.c | 1307 +++++++++++------------------------------- 1 file changed, 341 insertions(+), 966 deletions(-) diff --git a/src/library/libbwc.c b/src/library/libbwc.c index b886f64..1d66076 100755 --- a/src/library/libbwc.c +++ b/src/library/libbwc.c @@ -78,23 +78,17 @@ || | | \ | \/ | | | |___ | |__| | \| |___ | | |__| | \| ___] || || || \************************************************************************************************************/ -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function takes an integer value and generates a version with the appropri- ! -! ate byte unit in log2 format that is returned to the function caller. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 03.05.2019 Patrick Vogler B87D120 V 0.1.0 function created ! -! 04.05.2021 Patrick Vogler B87E7E4 V 0.1.0 clean up ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ #ifdef BWC_PROFILE +/*================================================================================================*/ +/** + * @details Takes an integer value and generates a version with the appropriate byte unit in + * log2 format as return value string. + * + * @param[in] integer Integer value of bytes. + * + * @retval const char* + */ +/*================================================================================================*/ const char* get_size(uint64_t integer) { @@ -144,41 +138,20 @@ } #endif -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uint8 initialize_precinct(bwc_codec *const codec, bwc_precinct *precinct, ! -! -------------- const uint32 dX, const uint32 dY, ! -! const uint32 dZ, const uint32 dTS) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! precinct bwc_precinct* - Structure defining a bwc precinct. ! -! ! -! dX, dY, dZ, dTS unsigned int(32 bit) - Defines the offset of the codeblock ! -! with regards to the current subband. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! unsigned int (8 bit) - Subband gain factor in log2 factor. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 24.05.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Initializes the precinct layout. + * + * @param[in] codec Structure defining the (de)compression codec. + * @param[inout] precinct Structure defining the precinct. + * @param[in] dX Codeblock offset with regard to the current subband in the 1st dimension. + * @param[in] dY Codeblock offset with regard to the current subband in the 2nd dimension. + * @param[in] dZ Codeblock offset with regard to the current subband in the 3rd dimension. + * @param[in] dTS Codeblock offset with regard to the current subband in the 4th dimension. + * + * @retval uint8_t + */ +/*================================================================================================*/ static uint8 initialize_precinct(bwc_codec *const codec, bwc_precinct *precinct, const uint32 dX, const uint32 dY, const uint32 dZ, const uint32 dTS) @@ -327,38 +300,17 @@ initialize_precinct(bwc_codec *const codec, bwc_precinct *precinct, const uint32 return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uint8 subband_gain(const uint8 highband_flag) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function calculates the gain for a specific subband in log2 format according to the ! -! number of applied 1-D wavelet transforms. The subband gain is calculated by evaluating the ! -! hamming weight of the highband flag. (see https://en.wikipedia.org/wiki/Hamming_weight) ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! highband_flag unsigned in (8 bit) - Flag defining the number and types of ! -! 1-D wavelet of transforms applied to ! -! the subband. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! unsigned int (8 bit) - Subband gain factor in log2 factor. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.05.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Calculates the gain for a specific subband in log2 format according to the number of + * applied 1-D wavelet transforms. The subband gain is calculated by evaluating the + * hamming weight of the highband flag. (see https://en.wikipedia.org/wiki/Hamming_weight) + * + * @param[in] highband_flag Number and types of transforms applied to the subband. + * + * @retval uint8_t Subband gain factor in log2 factor. + */ +/*================================================================================================*/ static uint8 subband_gain(const uint8 highband_flag) { /*-----------------------*\ @@ -385,53 +337,20 @@ static uint8 subband_gain(const uint8 highband_flag) return (temp + (temp >> 4)) & 0x0F; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar initialize_subband(bwc_codec *const codec, bwc_parameter *const parameter, ! -! -------------- bwc_resolution *const resolution, ! -! bwc_subband *const subband, ! -! int32 resolution_level, ! -! int16 highband_flag) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function initializes the bwc_subband structure with all necessary standard parameters ! -! to (de)compress a floating point array with nX * nY * nZ grid points, nTS timesteps and ! -! nPar parameters. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! parameter bwc_parameter* - Structure defining a bwc tile parameter.! -! ! -! resolution bwc_resolution* - Structure defining a bwc resolution ! -! level. ! -! ! -! subband bwc_subband* - Structure defining a bwc subband. ! -! ! -! resolution_level signed int(32 bit) - Defines the current resolution level. ! -! ! -! highband_flag signed int(16 bit) - Defines the type of highband the cur- ! -! rent subband represents. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! uchar - Returns an unsigned char for error handling. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 12.12.2017 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Initializes the bwc_subband structure. + * + * @param[in] codec Structure defining the (de)compression codec. + * @param[in] parameter Data of given parameter/field. + * @param[in] resolution Structure defining the resolution level. + * @param[in] subband Structure defining te subband. + * @param[in] resolution_level Current resolution level index. + * @param[in] highband_flag Type of highband that the current subband represents. + * + * @retval unsigned char + */ +/*================================================================================================*/ static uchar initialize_subband(bwc_codec *const codec, bwc_parameter *const parameter, bwc_resolution *const resolution, bwc_subband *const subband, @@ -682,55 +601,18 @@ initialize_subband(bwc_codec *const codec, bwc_parameter *const parameter, bwc_r return 0; } - -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void fill_buffer(bwc_codec *const codec, bwc_tile *const tile, ! -! ------------ bwc_parameter *const parameter, ! -! bwc_sample *const working_buffer, ! -! double *const data, ! -! uint64 param_size, ! -! uint16 param_id) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function is used to fill the working buffer with the appropriate flow field data for ! -! the specified tile parameter. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! tile bwc_tile* - Structure defining a bwc tile. ! -! ! -! parameter bwc_parameter* - Structure defining a bwc parameter. ! -! ! -! working_buffer bwc_sample* - Working buffer used to store flow field ! -! data for a specific tile parameter. ! -! ! -! param_size uint64 - Specifies the byte size of one tile ! -! parameter. ! -! ! -! parameter uint16 - Specifies the parameter index for the ! -! current tile parameter. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 22.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Fills the working buffer with the flow field data before compression. + * + * @param[in] codec Structure defining the (de)compression codec. + * @param[in] tile Structure defining a bwc tile. + * @param[in] parameter Data of given parameter/field. + * @param[inout] working_buffer Buffer which stores the flow field for compression. + * @param[in] data Instance of bwc_stream type with the flow field data. + * @param[in] param_id Parameter index for the current tile parameter. + */ +/*================================================================================================*/ static void fill_buffer(bwc_codec *const codec, bwc_tile *const tile, bwc_parameter *const parameter, bwc_sample *const working_buffer, @@ -924,53 +806,18 @@ fill_buffer(bwc_codec *const codec, bwc_tile *const tile, bwc_parameter *const p param_control->beta = 2.0f/(param_info->parameter_max - param_info->parameter_min); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void fill_buffer(bwc_codec *const codec, bwc_tile *const tile, ! -! ------------ bwc_parameter *const parameter, ! -! bwc_sample *const working_buffer, ! -! double *const data, ! -! uint64 param_size, ! -! uint16 param_id) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function is used to flush the working buffer to the flow field data memory block. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! tile bwc_tile* - Structure defining a bwc tile. ! -! ! -! parameter bwc_parameter* - Structure defining a bwc parameter. ! -! ! -! working_buffer bwc_sample* - Working buffer used to store flow field ! -! data for a specific tile parameter. ! -! ! -! param_size uint64 - Specifies the byte size of one tile ! -! parameter. ! -! ! -! parameter uint16 - Specifies the parameter index for the ! -! current tile parameter. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 22.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Flushes the working buffer to the flow field data memory block after decompression. + * + * @param[in] codec Structure defining the (de)compression codec. + * @param[in] tile Structure defining a bwc tile. + * @param[in] parameter Data of given parameter/field. + * @param[in] working_buffer Buffer which stores the flow field during decompression. + * @param[inout] data Instance of bwc_stream type that the flow field data is flushed to. + * @param[in] param_id Parameter index for the current tile parameter. + */ +/*================================================================================================*/ static void flush_buffer(bwc_codec *const codec, bwc_tile *const tile, bwc_parameter *const parameter, bwc_sample *const working_buffer, @@ -1125,43 +972,18 @@ flush_buffer(bwc_codec *const codec, bwc_tile *const tile, bwc_parameter *const } } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void normalize_param(bwc_codec *const codec, bwc_parameter *const parameter) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function is used to normalize the values v[i] of the current tile parameter to the ! -! range of [-1, 1) and scale them to a desired dynamic range: ! -! ! -! q[i] = [(v[i] - α)/β] * 2^Qm. ! -! ! -! Here, α and β define the normalization constants and Qm represents the dynamic range of ! -! the Q number format. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! parameter bwc_parameter* - Structure defining a bwc parameter. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 24.10.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Used to normalize the values v[i] of the current tile parameter to the range of [-1, 1) + * and scale them to a desired dynamic range: + * q[i] = [(v[i] - α)/β] * 2^Qm. + * Here, α and β define the normalization constants and Qm represents the dynamic range + * of the Q number format. + * + * @param[inout] codec Structure defining the (de)compression codec. + * @param[in] parameter Data of given parameter/field. + */ +/*================================================================================================*/ static void normalize_param(bwc_codec *const codec, bwc_parameter *const parameter) { @@ -1250,43 +1072,18 @@ normalize_param(bwc_codec *const codec, bwc_parameter *const parameter) } } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void denormalize_param(bwc_codec *const codec, bwc_parameter *const parameter) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function is used to scale the decompressed values to their original dynamic range and ! -! denormalize the flow field values. ! -! ! -! q[i] = [(v[i]/2^Qm) * β] + α. ! -! ! -! Here, α and β define the normalization constants and Qm represents the dynamic range of ! -! the Q number format. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! parameter bwc_parameter* - Structure defining a bwc parameter. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 24.10.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Used to scale the decompressed values to their original dynamic range and denormalize + * the flow field values. + * q[i] = [(v[i]/2^Qm) * β] + α. + * Here, α and β define the normalization constants and Qm represents the dynamic range + * of the Q number format. + * + * @param[inout] codec Structure defining the (de)compression codec. + * @param[in] parameter Data of given parameter/field. + */ +/*================================================================================================*/ static void denormalize_param(bwc_codec *const codec, bwc_parameter *const parameter) { @@ -1373,19 +1170,13 @@ denormalize_param(bwc_codec *const codec, bwc_parameter *const parameter) } } -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function allocates an instance of type bwc_codec and stores the codec precision. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! bwc_codec* Defines the (de)compression data structure. ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Allocates an instance of type bwc_codec with the compile-time codec precision. + * + * @retval bwc_stream* + */ +/*================================================================================================*/ bwc_codec* alloc_codec() { @@ -1418,41 +1209,17 @@ alloc_codec() || | |__| |__] |___ | |___ | |__| | \| |___ | | |__| | \| ___] || || || \************************************************************************************************************/ -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: bwc_codec *bwc_init_stream(...) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function initializes the bwc_stream structure with all necessary parameters. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! prec bwc_precision - Input data precision ! -! ! -! nX ,nY, nZ unsigned int(64 bit) - Number of spatial Datapoints ! -! ! -! nTS unsigned int(16 bit) - Number of Timesteps. ! -! ! -! nPar unsigned int(8 bit) - Number of Parameters ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! bwc_stream* - Structure used to store a numerical ! -! dataset/compressed bitstream. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 09.06.2021 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Allocates and assigns user-owned pointers for (de)compression input and output. + * + * @param[in] inpbuf Input data. Can be compressed or original flow field data. + * @param[in] outbuf Output pointer which must have enough space for given output. + * @param[in] mode Decides the mode to be input for compression or decompression (comp | decomp). + * + * @retval bwc_stream* + */ +/*================================================================================================*/ bwc_stream* bwc_init_stream(void *const inpbuf, void *const outbuf, bwc_mode const mode) { @@ -1476,15 +1243,18 @@ bwc_init_stream(void *const inpbuf, void *const outbuf, bwc_mode const mode) return stream; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: ! -! -------------- ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends a user-defined comment in the bwc_codec structure. Can be used to comment the + * compressed data with user-defined information that helps data interpretation. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] com Commentary string. + * @param[in] size Size of commentary string. + * + * @retval unsigned char + */ +/*================================================================================================*/ uchar bwc_set_com(bwc_stream *const data, char const *const com, uint16 size) { @@ -1515,15 +1285,18 @@ bwc_set_com(bwc_stream *const data, char const *const com, uint16 size) return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: ! -! -------------- ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the auxiliary information in the bwc_codec structure. Can be used to store and + * retrieve file format specific metadata. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] aux Auxiliary information string. + * @param[in] size Size of auxiliary information string. + * + * @retval unsigned char + */ +/*================================================================================================*/ uchar bwc_set_aux(bwc_stream *const data, char const *const aux, uint32 size) { @@ -1554,36 +1327,15 @@ bwc_set_aux(bwc_stream *const data, char const *const aux, uint32 size) return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar create_codec(bwc_codec *const codec) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function creates the codec structure used to (de)compress a floating point array de- ! -! fined by the bwc_initialize function. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! unsigned char - Returns an unsigned char for error handling. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Creates intrinsics like tile and subband structure in a valid codec instance. + * + * @param[inout] codec Structure defining the compression coder. + * + * @retval unsigned char + */ +/*================================================================================================*/ uchar create_codec(bwc_codec *const codec) { @@ -1958,39 +1710,13 @@ create_codec(bwc_codec *const codec) return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_free_compression(bwc_codec *const codec) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function deallocates the compression codec structure used to define and control the ! -! bwc codec and can be called if an error occurs during the (de-)compression stage or once ! -! the codec has finished. The deallocation will be carried out down to the structure levels ! -! that have been allocated. ! -! ! -! PARAMETERS: ! -! ----------- ! -! ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 19.10.2017 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Deallocates the (de)compression codec structure and contained resources. + * + * @param[inout] codec Structure defining the compression coder. + */ +/*================================================================================================*/ void bwc_free_codec(bwc_codec *const codec) { @@ -2078,21 +1804,21 @@ bwc_free_codec(bwc_codec *const codec) } } -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function configures the bwc_codec structure with all necessary standard parameters ! -! to compress a floating point array with nX * nY * nZ grid points, nTS timesteps and ! -! nPar parameters. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! bwc_codec* Defines the (de)compression data structure. ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Configures the bwc_codec structure for compression with given dimensions and precision. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] nX Field data size in first dimension. + * @param[in] nY Field data size in two dimension. + * @param[in] nZ Field data size in three dimension. + * @param[in] nTS Field data size in fourth dimension. + * @param[in] nPar Number of parameters. + * @param[in] prec Data precision. + * + * @retval bwc_codec* + */ +/*================================================================================================*/ bwc_codec* configure_codec(bwc_codec *const codec, uint64 const nX, uint64 const nY, uint64 const nZ, uint64 const nTS, uint8 const nPar, bwc_precision const prec) @@ -2250,21 +1976,20 @@ configure_codec(bwc_codec *const codec, uint64 const nX, uint64 const nY, uint64 return codec; } -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function initializes the bwc_codec structure with all necessary standard parameters ! -! to (de)compress a floating point array with nX * nY * nZ grid points, nTS timesteps and ! -! nPar parameters. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! bwc_codec* Defines the (de)compression data structure. ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Allocates the bwc_codec structure for compression with given dimensions and precision. + * + * @param[in] nX Field data size in first dimension. + * @param[in] nY Field data size in two dimension. + * @param[in] nZ Field data size in three dimension. + * @param[in] nTS Field data size in fourth dimension. + * @param[in] nPar Number of parameters. + * @param[in] prec Data precision. + * + * @retval bwc_codec* + */ +/*================================================================================================*/ bwc_codec* bwc_alloc_coder(uint64 const nX, uint64 const nY, uint64 const nZ, uint64 const nTS, uint8 const nPar, bwc_precision const prec) @@ -2279,21 +2004,13 @@ bwc_alloc_coder(uint64 const nX, uint64 const nY, uint64 const nZ, uint64 const return codec; } -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function initializes the bwc_codec structure with all necessary standard parameters ! -! to (de)compress a floating point array with nX * nY * nZ grid points, nTS timesteps and ! -! nPar parameters. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! bwc_codec* Defines the (de)compression data structure. ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Allocates the bwc_codec structure for decompression. + * + * @retval bwc_codec* + */ +/*================================================================================================*/ bwc_codec* bwc_alloc_decoder() { @@ -2306,36 +2023,13 @@ bwc_alloc_decoder() return codec; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_error_resilience(bwc_codec *const codec) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function sets the error resilience marker in the bwc_codec structure if an error ! -! resilient compression approach is to be employed. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 13.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Turns on the error resilience marker in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + */ +/*================================================================================================*/ void bwc_set_error_resilience(bwc_codec *const codec) { @@ -2368,39 +2062,14 @@ bwc_set_error_resilience(bwc_codec *const codec) control->CSsgc ^= (0x01 << 0); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_quant_style(bwc_codec *const codec, bwc_quant_st quantization_style) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the quantization style in the bwc_codec structure according to the ! -! specified value. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! quantization_style bwc_quant_st - Quantization style used during compres- ! -! sion. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the quantization style in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] quantization_sytle Quantization style employed during compression. + */ +/*================================================================================================*/ void set_quant_style(bwc_codec *const codec, bwc_quant_st quantization_style) { @@ -2434,39 +2103,14 @@ set_quant_style(bwc_codec *const codec, bwc_quant_st quantization_style) control->CSsgc |= (0x01 << 1); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_quant_step_size(bwc_codec *const codec, double delta) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the quantization step size in the bwc_codec structure according to ! -! the specified value. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! delta double - Quantization step size used during ! -! compression. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 16.04.2019 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the quantization step size in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] delta Quantization step size employed during compression. + */ +/*================================================================================================*/ void set_quant_step_size(bwc_codec *const codec, double delta) { @@ -2537,40 +2181,14 @@ set_quant_step_size(bwc_codec *const codec, double delta) control->CSsgc |= (0x01 << 2); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void set_progression(bwc_codec *const codec, bwc_prog_ord progression) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the progression order in the bwc_codec structure according to the ! -! specified value. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! progression bwc_prog_ord - Progression orders employed during com- ! -! pression (CPRL, LRCP, PCRL, RLCP, ! -! RPCL). ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the progression order in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] progression Progression orders employed during compression. + */ +/*================================================================================================*/ void set_progression(bwc_codec *const codec, bwc_prog_ord progression) { @@ -2606,44 +2224,17 @@ set_progression(bwc_codec *const codec, bwc_prog_ord progression) control->CSsgc |= (0x01 << 3); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void set_kernels(bwc_codec *const codec, bwc_dwt_filter KernelX, ! -! -------------- bwc_dwt_filter KernelY, ! -! bwc_dwt_filter KernelZ, ! -! bwc_dwt_filter KernelTS) ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the wavelet kernels in the bwc_codec structure according to the ! -! specified values. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! KernelX, KernelY, KernelZ bwc_dwt_filter - Wavelet kernels used for spatial ! -! decomposition. ! -! ! -! KernelT bwc_dwt_filter - Wavelet kernel used for temporal ! -! decomposition. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the wavelet kernels in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] KernelX Wavelet kernel used in first dimemsion in log2 exponent format. + * @param[in] KernelY Wavelet kernel used in first dimemsion in log2 exponent format. + * @param[in] KernelZ Wavelet kernel used in third dimemsion in log2 exponent format. + * @param[in] KernelTS Wavelet kernel used in fourth dimemsion in log2 exponent format. + */ +/*================================================================================================*/ void set_kernels(bwc_codec *const codec, bwc_dwt_filter KernelX, bwc_dwt_filter KernelY, bwc_dwt_filter KernelZ, bwc_dwt_filter KernelTS) @@ -2682,42 +2273,17 @@ set_kernels(bwc_codec *const codec, bwc_dwt_filter KernelX, bwc_dwt_filter Kerne control->CSsgc |= (0x01 << 4); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_decomp(bwc_codec *const codec, uint8 decompX, uint8 decompY, ! -! -------------- uint8 decompZ, uint8 decompTS) ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the decomposition levels in the bwc_codec structure according to the ! -! specified values. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! decompX, decompY, decompZ unsigned int(8 bit) - Number of spatial wavelet decomposition ! -! levels used during compression. ! -! ! -! decompTS unsigned int(8 bit) - Number of temporal wavelet decomposi- ! -! tion level used during compression. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 14.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the decomposition levels in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] decompX Number of wavelet decomposition levels in first dimemsion in log2 exponent format. + * @param[in] decompY Number of wavelet decomposition levels in first dimemsion in log2 exponent format. + * @param[in] decompZ Number of wavelet decomposition levels in third dimemsion in log2 exponent format. + * @param[in] decompTS Number of wavelet decomposition levels in fourth dimemsion in log2 exponent format. + */ +/*================================================================================================*/ void bwc_set_decomp(bwc_codec *const codec, uint8 decompX, uint8 decompY, uint8 decompZ, uint8 decompTS) { @@ -2849,39 +2415,17 @@ bwc_set_decomp(bwc_codec *const codec, uint8 decompX, uint8 decompY, uint8 decom control->CSsgc |= (0x01 << 5); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_precincts(bwc_codec *const codec, uint8 pX, uint8 pY, uint8 pZ, uint8 pTS) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the precinct size in the bwc_codec structure according to the ! -! specified values. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! px, py, pz, pTS unsigned int(8 bit) - Spatial and temporal precinct dimensions! -! in log2 exponent format. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.05.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the precinct size in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] pX Precinct size in first dimemsion in log2 exponent format. + * @param[in] pY Precinct size in first dimemsion in log2 exponent format. + * @param[in] pZ Precinct size in third dimemsion in log2 exponent format. + * @param[in] pTS Precinct size in fourth dimemsion in log2 exponent format. + */ +/*================================================================================================*/ void bwc_set_precincts(bwc_codec *const codec, uint8 pX, uint8 pY, uint8 pZ, uint8 pTS) { @@ -2949,39 +2493,17 @@ bwc_set_precincts(bwc_codec *const codec, uint8 pX, uint8 pY, uint8 pZ, uint8 pT control->CSsgc |= (0x01 << 6); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_codeblocks(bwc_codec *const codec, uint8 cbX, uint8 cbY, ! -! -------------- uint8 cbZ, uint8 cbTS) ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the codeblock size in the bwc_codec structure according to the ! -! specified values. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! cbx, cby, cbz, cbTS unsigned int(8 bit) - Spatial and temporal codeblock dimen- ! -! sions in log2 exponent format. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 14.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the codeblock size in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] cbX Codeblock size in first dimemsion in log2 exponent format. + * @param[in] cbY Codeblock size in first dimemsion in log2 exponent format. + * @param[in] cbZ Codeblock size in third dimemsion in log2 exponent format. + * @param[in] cbTS Codeblock size in fourth dimemsion in log2 exponent format. + */ +/*================================================================================================*/ void bwc_set_codeblocks(bwc_codec *const codec, uint8 cbX, uint8 cbY, uint8 cbZ, uint8 cbTS) { @@ -3049,38 +2571,14 @@ bwc_set_codeblocks(bwc_codec *const codec, uint8 cbX, uint8 cbY, uint8 cbZ, uint control->CSsgc |= (0x01 << 7); } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_qm(bwc_codec *const codec, uint8 Qm) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the Q number formate range in the bwc_codec structure according to the ! -! specified value. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! Qm unsigned int(8 bit) - Q number formate range (m). ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 14.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the Q number formate range in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] Qm Q number formate range (m). + */ +/*================================================================================================*/ void bwc_set_qm(bwc_codec *const codec, uint8 Qm) { @@ -3129,46 +2627,18 @@ bwc_set_qm(bwc_codec *const codec, uint8 Qm) } } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_set_tiles(bwc_codec *const codec, uint32 tilesX, uint32 tilesY, uint32 tilesZ, ! -! -------------- uint32 tilesTS, uchar instr) ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function amends the tileSize and num_Tiles values in the bwc_codec structure according ! -! to the specified values. The NUMBEROF and SIZEOF constants can be used to either specify ! -! the tile sizes or the number of tiles in each spatial and temporal directions. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! tilesX, tilesY, tilesZ unsigned int(32 bit) - Variables defining the size of ! -! a spatial tile. ! -! ! -! tilesTS unsigned int(32 bit) - Variables defining the size of ! -! a temporal tile. ! -! ! -! instr bwc_tile_instr - Constants used to instruct the ! -! bwc_set_tiles function. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 14.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Amends the tileSize and num_Tiles values in the bwc_codec structure. + * + * @param[inout] codec Structure defining the compression coder. + * @param[in] tilesX Spatial tile size/number in first dimension. + * @param[in] tilesY Spatial tile size/number in second dimension. + * @param[in] tilesZ Spatial tile size/number in third dimension. + * @param[in] tilesTS Spatial tile size/number in fourth dimension. + * @param[in] instr Instructs interpretation of parameters as 'size' or 'number'. + */ +/*================================================================================================*/ void bwc_set_tiles(bwc_codec *const codec, uint64 tilesX, uint64 tilesY, uint64 tilesZ, uint64 tilesTS, bwc_tile_instr instr) { @@ -3354,7 +2824,7 @@ bwc_set_tiles(bwc_codec *const codec, uint64 tilesX, uint64 tilesY, uint64 tiles /*================================================================================================*/ /** - * @details This function opens the header of a compressed data set and parses it into an + * @details Opens the header of a compressed data set and parses it into an * instance of type bwc_header. * * @param[in] inpbuf Pointer to compressed data set. @@ -3422,7 +2892,7 @@ bwc_header* bwc_open_header(void *const inpbuf) /*================================================================================================*/ /** - * @details This function closes the header information in the bwc_header pointer. + * @details Closes the header information in the bwc_header pointer. * * @param[in] header Instance of type bwc_header. */ @@ -3443,44 +2913,18 @@ void bwc_close_header(bwc_header *const header) } } - -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: void bwc_create_compression(bwc_codec *codec, char *rate_control) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function creates the codec structure used to compress a floating point array defined ! -! by the bwc_initialize function. For a compression run, the rate_control and instr arguments ! -! need to be passed to the function to properly set up the lossy compression stage. Here, the ! -! instr parameter defines whether rate control is defined by a BITRATE - a floating point val-! -! ue defining the average number of bits per datapoint - and ACCURACY - an integer value de- ! -! fining the exponent of the maximum allowable error (i.e. 15 for err = 1e-15). ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! rate_control char* - Variable defining the bitrate. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! 05.12.2019 Patrick vogler B87E7E4 V 0.1.0 streamlined function arguments ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Creates the codec structure used to compress floating point data in a previously + * initialized instance of the bwc_stream structure. + * + * @param[inout] codec Pointer to the returned codec structure. + * @param[in] stream Stream data structure containing the relevant floating point data. + * @param[in] rate_control The bitrates of several quality layers as string variable. + * + * @retval uchar + */ +/*================================================================================================*/ uchar bwc_create_compression(bwc_codec *codec, bwc_stream *stream, char *rate_control) { @@ -3645,37 +3089,19 @@ bwc_create_compression(bwc_codec *codec, bwc_stream *stream, char *rate_control) return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar bwc_compress(bwc_codec *const codec, bwc_float *const data) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! Description needed. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! uchar - Returns an unsigned char for error handling. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Compress the data of a readily initialized bwc_stream structure using the coder + * defined by the codec variable. + * + * @param[inout] codec Pointer to the returned codec structure. + * @param[in] stream Stream data structure containing the relevant floating point data. + * + * @retval size_t + */ +/*================================================================================================*/ size_t -bwc_compress(bwc_codec *const codec, bwc_stream *const data) +bwc_compress(bwc_codec *const codec, bwc_stream *const stream) { /*-----------------------*\ ! DEFINE INT VARIABLES: ! @@ -3722,7 +3148,7 @@ bwc_compress(bwc_codec *const codec, bwc_stream *const data) ! DEFINE ASSERTIONS: ! \*-----------------------*/ assert(codec); - assert(data); + assert(stream); /*--------------------------------------------------------*\ ! Initialize the compression time measurement. ! @@ -3788,7 +3214,7 @@ bwc_compress(bwc_codec *const codec, bwc_stream *const data) start = (double)clock(); #endif #endif - fill_buffer(codec, tile, parameter, working_buffer, data, p); + fill_buffer(codec, tile, parameter, working_buffer, stream, p); #ifdef BWC_PROFILE #if defined (_OPENMP) end = omp_get_wtime(); @@ -3913,7 +3339,7 @@ bwc_compress(bwc_codec *const codec, bwc_stream *const data) start = (double)clock(); #endif #endif - compressed_size = assemble_codestream(codec, data); + compressed_size = assemble_codestream(codec, stream); if(compressed_size == 0) { free(working_buffer); @@ -3970,42 +3396,18 @@ bwc_compress(bwc_codec *const codec, bwc_stream *const data) return compressed_size; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar bwc_create_compression(bwc_codec *const codec, bwc_stream *const stream, ! -! -------------- uint8 layer) ! -! ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function parses the supplied bwc codestream and sets up the codec structure used to ! -! decompress the numerical dataset. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! rate_control (opt) char* - Variable defining the bitrate/accuracy. ! -! ! -! instr (opt) bwc_rate_instr - Constants used to instruct the rate ! -! control information. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Creates the codec structure used to decompress floating point data in a previously + * initialized instance of the bwc_stream structure. + * + * @param[inout] codec Pointer to the returned codec structure. + * @param[in] stream Stream data structure containing the relevant floating point data. + * @param[in] layer Number of quality layers. + * + * @retval uchar + */ +/*================================================================================================*/ uchar bwc_create_decompression(bwc_codec *const codec, bwc_stream *const stream, uint8 layer) { @@ -4027,46 +3429,19 @@ bwc_create_decompression(bwc_codec *const codec, bwc_stream *const stream, uint8 return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar bwc_create_compression(bwc_codec *codec, float rate_control, uchar instr) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function creates the codec structure used to compress a floating point array defined ! -! by the bwc_initialize function at a prescribed bitrate or accuracy. In this context, the ! -! bitrate is a floating point value defining the average number of bits per datapoint and ! -! the accuracy is an integer value defining the exponent of the maximum allowable error ! -! (i.e. 15 for err = 1e-15). ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! codec bwc_codec* - Structure defining the compression/ ! -! decompression stage. ! -! ! -! rate_control float - Variable defining the bitrate/accuracy. ! -! ! -! instr unsigned char - Constants used to instruct the rate ! -! control information. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 15.03.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Decompress the data of a readily initialized bwc_stream structure using the coder + * defined by the codec variable. + * + * @param[inout] codec Pointer to the returned codec structure. + * @param[in] stream Stream data structure containing the relevant floating point data. + * + * @retval uchar + */ +/*================================================================================================*/ uchar -bwc_decompress(bwc_codec *const codec, bwc_stream *const data) +bwc_decompress(bwc_codec *const codec, bwc_stream *const stream) { /*-----------------------*\ ! DEFINE INT VARIABLES: ! @@ -4103,7 +3478,7 @@ bwc_decompress(bwc_codec *const codec, bwc_stream *const data) ! DEFINE ASSERTIONS: ! \*-----------------------*/ assert(codec); - assert(data); + assert(stream); /*--------------------------------------------------------*\ ! Initialize the decompression time measurement. ! @@ -4248,7 +3623,7 @@ bwc_decompress(bwc_codec *const codec, bwc_stream *const data) start = (double)clock(); #endif #endif - flush_buffer(codec, tile, parameter, working_buffer, data, p); + flush_buffer(codec, tile, parameter, working_buffer, stream, p); #ifdef BWC_PROFILE #if defined (_OPENMP) end = omp_get_wtime();