diff options
Diffstat (limited to 'doxygen/dox/high_level/extension.dox')
| -rw-r--r-- | doxygen/dox/high_level/extension.dox | 654 |
1 files changed, 0 insertions, 654 deletions
diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox deleted file mode 100644 index c81ac6e..0000000 --- a/doxygen/dox/high_level/extension.dox +++ /dev/null @@ -1,654 +0,0 @@ -/** \defgroup H5LR Extensions - * - * <em>Working with region references, hyperslab selections, - * and bit-fields (H5LR, H5LT)</em> - * - * The following reference manual entries describe high-level HDF5 C and Fortran APIs - * for working with region references, hyperslab selections, and bit-fields. - * These functions were created as part of a project supporting - * NPP/NPOESS Data Production and Exploitation ( - * <a href="https://support.hdfgroup.org/projects/jpss/documentation"> - * project </a>, - * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> - * software </a>). - * While they were written to facilitate access to NPP, NPOESS, and JPSS - * data in the HDF5 format, these functions may be useful to anyone working - * with region references, hyperslab selections, or bit-fields. - * - * Note that these functions are not part of the standard HDF5 distribution; - * the - * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> - * software </a> - * must be separately downloaded and installed. - * - * A comprehensive guide to this library, - * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf"> - * <em>User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections</em></a> - * is available at - * https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf. - * - * - \ref H5LRcopy_reference - * \n Copies data from the specified dataset to a new location and - * creates a reference to it. - * - \ref H5LRcopy_region - * \n Copies data from a referenced region to a region in a - * destination dataset. - * - \ref H5LRcreate_ref_to_all - * \n Creates a dataset with the region references to the data in all - * datasets located under a specified group in a file or creates a - * dataset with object references to all objects (groups or datasets) - * located under a specified group in a file. - * - \ref H5LRcreate_region_references - * \n Creates an array of region references using an array of paths to - * datasets and an array of corresponding hyperslab descriptions. - * - \ref H5LRget_region_info - * \n Retrieves information about the data a region reference points to. - * - \ref H5LRmake_dataset - * \n Creates and writes a dataset containing a list of - * region references. - * - \ref H5LRread_region - * \n Retrieves raw data pointed to by a region reference to - * an application buffer. - * - \ref H5LTcopy_region - * \n Copies data from a specified region in a source dataset - * to a specified region in a destination dataset. - * - \ref H5LTread_bitfield_value - * \n Retrieves the values of quality flags for each element - * to the application provided buffer. - * - \ref H5LTread_region - * \n Reads selected data to an application buffer. - * - */ - -/*------------------------------------------------------------------------- - * - * Make dataset functions - * - *------------------------------------------------------------------------- - */ - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Creates and writes a dataset containing a list of region references. - * - * \fgdta_loc_id - * \param[in] path Path to the dataset being created - * \param[in] type_id Datatype of the dataset - * \param[in] buf_size Size of the \p loc_id_ref and \p buf arrays - * \param[in] loc_id_ref Array of object identifiers; each identifier - * describes to which HDF5 file the corresponding - * region reference belongs to - * \param[in] buf Array of region references - * - * \return \herr_t - * - * \details Given an array of size \p buf_size of region references \p buf, - * the function will create a dataset with path \p path, at location - * specified by \p loc_id and of a datatype specified by \p type_id, - * and will write data associated with each region reference in the order - * corresponding to the order of the region references in the buffer. - * It is assumed that all referenced hyperslabs have the same dimensionality, - * and only the size of the slowest changing dimension may differ. - * Each reference in the \p buf array belongs to the file identified - * by the corresponding object identifiers in the array \p loc_id_ref. - * - * If \p path does not exist in \p loc_id then the function will - * create the path specified by \p path automatically. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRmake_dataset(hid_t loc_id, - const char *path, - hid_t type_id, const size_t buf_size, - const hid_t *loc_id_ref, - const hdset_reg_ref_t *buf); - -/*------------------------------------------------------------------------- - * - * Make and manipulate dataset region references functions - * - *------------------------------------------------------------------------- - */ - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Creates an array of region references using an array of paths to - * datasets and an array of corresponding hyperslab descriptions. - * - * \param[in] obj_id File identifier for the HDF5 file containing - * the referenced regions or an object identifier - * for any object in that file - * \param[in] num_elem Number of elements in the \p path and - * \p buf arrays - * \param[in] path Array of pointers to strings, which contain - * the paths to the target datasets for the - * region references - * \param[in] block_coord Array of hyperslab coordinate - * \param[out] buf Buffer for returning an array of region - * references - * - * \return \herr_t - * - * \note **Motivation:** - * \note H5LRcreate_region_references() is useful when creating - * large numbers of similar region references. - * - * \details H5LRcreate_region_references() creates a list of region references - * given an array of paths to datasets and another array listing the - * corner coordinates of the corresponding hyperslabs. - * - * \p path parameter is an array of pointers to strings. - * - * \p num_elem specifies the number of region references to be created, - * thus specifying the size of the \p path and \p _buf arrays. - * - * Buffer \p block_coord has size 2*rank and is the coordinates of the - * starting point following by the coordinates of the ending point of - * the hyperslab, repeated \p num_elem times for each hyperslab. - * For example, creating two region references to two hyperslabs, - * one with a rectangular hyperslab region starting at element (2,2) - * to element (5,4) and the second rectangular region starting at - * element (7,7) to element (9,10), results in \p block_coord - * being {2,2,5,4, 7,7,9,10}. - * - * The rank of the hyperslab will be the same as the rank of the - * target dataset. H5LRcreate_region_references() will retrieve - * the rank for each dataset and will use those values to interpret - * the values in the buffer. Please note that rank may vary from one - * dataset to another. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRcreate_region_references(hid_t obj_id, - size_t num_elem, - const char **path, - const hsize_t *block_coord, - hdset_reg_ref_t *buf); - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Copies data from the specified dataset to a new location and - * creates a reference to it. - * - * \param[in] obj_id Identifier of any object in a file an - * HDF5 reference belongs to - * \param[in] ref Reference to the datasets region - * \param[in] file Name of the destination file - * \param[in] path Full path to the destination dataset - * \param[in] block_coord Hyperslab coordinates in the destination - * dataset - * \param[out] ref_new Region reference to the new location of - * data - * - * \return \herr_t - * - * \details Given a data set pointed to by a region reference, the function - * H5LRcopy_reference() will copy the hyperslab data referenced by - * a datasets region reference into existing dataset specified by - * its path \p path in the file with the name \p file, and to location - * specified by the hyperslab coordinates \p block_coord. It will - * create the region reference \p ref_new to point to the new location. - * The number of elements in the old and newly specified regions has - * to be the same. - * - * Buffer \p block_coord has size 2*rank and is the coordinates of - * the starting point following by the coordinates of the ending - * point of the hyperslab. For example, to extract a rectangular - * hyperslab region starting at element (2,2) to element (5,4) - * then \p block_coord would be {2, 2, 5, 4}. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRcopy_reference(hid_t obj_id, hdset_reg_ref_t *ref, const char *file, - const char *path, const hsize_t *block_coord, - hdset_reg_ref_t *ref_new); - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Copies data from a referenced region to a region in a - * destination dataset. - * - * \param[in] obj_id Identifier of any object in a file - * dataset region reference belongs to - * \param[in] ref Dataset region reference - * \param[in] file Name of the destination file - * \param[in] path Full path to the destination dataset - * \param[in] block_coord Hyperslab coordinates in the destination - * dataset - * - * \return \herr_t - * - * \details Given a dataset region reference \p ref in a source file - * specified by an identifier of any object in that file - * \p obj_id, the function will write data to the existing - * dataset \p path in file \p file to the simple hyperslab - * specified by \p block_coord. - * - * Buffer \p block_coord has size 2*rank and is the coordinates - * of the starting point following by the coordinates of the - * ending point of the hyperslab. For example, to specify a - * rectangular hyperslab destination region starting at element - * (2,2) to element (5,4) then \p block_coord would be {2, 2, 5, 4}. - * - * If \p path does not exist in the destination file (as may be - * the case when writing to a new file) then the dataset will be - * copied directly to the \p path and \p block_coord will be - * disregarded. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRcopy_region(hid_t obj_id, - hdset_reg_ref_t *ref, - const char *file, - const char *path, - const hsize_t *block_coord); - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Creates a dataset with the region references to the data - * in all datasets located under a specified group in a file - * or creates a dataset with object references to all objects - * (groups or datasets) located under a specified group in a file. - * - * \fg_loc_id - * \param[in] group_path Absolute or relative path to the group - * at which traversal starts - * \param[in] ds_path Absolute or relative path to the dataset - * with region references to be created - * \param[in] index_type Index_type; - * see valid values below in description - * \param[in] order Order in which index is traversed; - * see valid values below in description - * \param[in] ref_type Reference type; - * see valid values below in description - * - * \return \herr_t - * - * \details H5LRcreate_ref_to_all() creates a dataset with the - * region references to the data in all datasets located - * under a specified group in a file or creates a dataset with - * object references to all objects (groups or datasets) located - * under a specified group in a file. - * - * Given a dataset path \p ds_path in a file specified by the - * \p loc_id identifier, the function H5LRcreate_ref_to_all() - * will create a contiguous one-dimensional dataset with the - * region references or object references depending on the value - * of the \p ref_type parameter. When \p ref_type is - * #H5R_DATASET_REGION, each region reference points to all data - * in a dataset encountered by an internally called H5Lvisit() - * routine, which starts at the group specified by the \p loc_id - * and \p group_path parameters. In a like manner, when - * \p ref_type is #H5R_OBJECT, each object reference points to - * an object (a group or a dataset) encountered by H5Lvisit(). - * - * If \p ds_path does not exist in \p loc_id then the function - * will create the path specified by \p ds_path automatically. - * - * \p index_type specifies the index to be used. - * Valid values include the following: - * - #H5_INDEX_NAME Alphanumeric index on name - * - #H5_INDEX_CRT_ORDER Index on creation order - * - * \p order specifies the order in which objects are to be - * inspected along the index specified in \p index_type. - * Valid values include the following: - * - #H5_ITER_INC Increasing order - * - #H5_ITER_DEC Decreasing order - * - #H5_ITER_NATIVE Fastest available order - * - * For more detailed information on these two parameters, - * see H5Lvisit(). - * - * \p ref_type specifies the type of the reference to be used. - * Valid values include the following: - * - #H5R_DATASET_REGION Dataset region reference - * - #H5R_OBJECT Object reference - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRcreate_ref_to_all(hid_t loc_id, const char *group_path, - const char *ds_path, H5_index_t index_type, H5_iter_order_t order, H5R_type_t ref_type); - -/*------------------------------------------------------------------------- - * - * Read dataset functions - * - *------------------------------------------------------------------------- - */ - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Retrieves raw data pointed to by a region reference - * to an application buffer. - * - * \param[in] obj_id File identifier for the HDF5 file containing - * the dataset with the referenced region or an - * object identifier for any object in that file - * \param[in] ref Region reference specifying data to be read - * in - * \param[in] mem_type Memory datatype of data read from referenced - * region into the application buffer - * \param[in,out] numelem Number of elements to be read into buffer - * \p buf - * \param[out] buf Buffer in which data is returned to the - * application - * - * \return \herr_t - * - * \details H5LRread_region() reads data pointed to by the region - * reference \p ref into the buffer \p buf. - * - * \p numelem specifies the number of elements to be read - * into \p buf. When the size of the reference region is unknown, - * H5LRread_region() can be called with \p buf set to NULL; - * the number of elements in the referenced region will be returned - * in \p numelem. - * - * The buffer buf must be big enough to hold \p numelem elements - * of type \p mem_type. For example, if data is read from the referenced - * region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT - * and the buffer must be at least \c sizeof(int) * \p numelem bytes - * in size. This buffer must be allocated by the application. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRread_region(hid_t obj_id, - const hdset_reg_ref_t *ref, - hid_t mem_type, - size_t *numelem, - void *buf ); - -/*------------------------------------------------------------------------- - * - * Query dataset functions - * - *------------------------------------------------------------------------- - */ - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Retrieves information about the data a region reference - * points to. - * - * \param[in] obj_id Identifier of any object in an HDF5 file - * the region reference belongs to. - * \param[in] ref Region reference to query - * \param[in,out] len Size of the buffer to store \p path in. - * NOTE: if \p *path is not NULL then \p *len - * must be the appropriate length - * \param[out] path Full path that a region reference points to - * \param[out] rank The number of dimensions of the dataset - * dimensions of the dataset pointed by - * region reference. - * \param[out] dtype Datatype of the dataset pointed by the - * region reference. - * \param[out] sel_type Type of the selection (point or hyperslab) - * \param[in,out] numelem Number of coordinate blocks or - * selected elements. - * \param[out] buf Buffer containing description of the region - * pointed by region reference - * - * \return \herr_t - * - * \details H5LRget_region_info() queries information about the data - * pointed by a region reference \p ref. It returns one of the - * absolute paths to a dataset, length of the path, dataset’s rank - * and datatype, description of the referenced region and type of - * the referenced region. Any output argument can be NULL if that - * argument does not need to be returned. - * - * The parameter \p obj_id is an identifier for any object in the - * HDF5 file containing the referenced object. For example, it can - * be an identifier of a dataset the region reference belongs to - * or an identifier of an HDF5 file the dataset with region references - * is stored in. - * - * The parameter \p ref is a region reference to query. - * - * The parameter \p path is a pointer to application allocated - * buffer of size \p len+1 to return an absolute path to a dataset - * the region reference points to. - * - * The parameter \p len is a length of absolute path string plus - * the \0 string terminator. If path parameter is NULL, actual - * length of the path (+1 for \0 string terminator) is returned to - * application and can be used to allocate buffer path of an - * appropriate length \p len. - * - * The parameter \p sel_type describes the type of the selected - * region. Possible values can be #H5S_SEL_POINTS for point - * selection and #H5S_SEL_HYPERSLABS for hyperslab selection. - * - * The parameter \p numelem describes how many elements will be - * placed in the buffer \p buf. The number should be interpreted - * using the value of \p sel_type. - * - * If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter - * \p buf contains \p numelem blocks of the coordinates for each - * simple hyperslab of the referenced region. Each block has - * length \c 2*\p rank and is organized as follows: <"start" coordinate>, - * immediately followed by <"opposite" corner coordinate>. - * The total size of the buffer to hold the description of the - * region will be \c 2*\p rank*\p numelem. If region reference - * points to a contiguous sub-array, then the value of \p numelem - * is 1 and the block contains coordinates of the upper left and - * lower right corners of the sub-array (or simple hyperslab). - * - * If value of \p sel_type is #H5S_SEL_POINTS, the parameter \p buf - * contains \p numelem blocks of the coordinates for each selected - * point of the referenced region. Each block has length \p rank - * and contains coordinates of the element. The total size of the - * buffer to hold the description of the region will be - * \p rank* \p numelem. - * - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LRget_region_info(hid_t obj_id, - const hdset_reg_ref_t *ref, - size_t *len, - char *path, - int *rank, - hid_t *dtype, - H5S_sel_type *sel_type, - size_t *numelem, - hsize_t *buf ); - - - -/*------------------------------------------------------------------------- - * - * Make dataset functions - * - *------------------------------------------------------------------------- - */ - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Copies data from a specified region in a source dataset - * to a specified region in a destination dataset - * - * \param[in] file_src Name of the source file - * \param[in] path_src Full path to the source dataset - * \param[in] block_coord_src Hyperslab coordinates in the - * source dataset - * \param[in] file_dest Name of the destination file - * \param[in] path_dest Full path to the destination dataset - * \param[in] block_coord_dset Hyperslab coordinates in the - * destination dataset - * - * \return \herr_t - * - * \details Given a path to a dataset \p path_src in a file with the - * name \p file_src, and description of a simple hyperslab of - * the source \p block_coord_src, the function will write data - * to the dataset \p path_dest in file \p file_dest to the - * simple hyperslab specified by \p block_coord_dset. - * The arrays \p block_coord_src and \p block_coord_dset have - * a length of 2*rank and are the coordinates of the starting - * point following by the coordinates of the ending point of the - * hyperslab. For example, to specify a rectangular hyperslab - * destination region starting at element (2,2) to element (5,4) - * then \p block_coord_dset would be {2, 2, 5, 4}. - * - * If \p path_dest does not exist in the destination file - * (as may be the case when writing to a new file) then the - * dataset will be copied directly to the \p path_dest and - * \p block_coord_dset will be disregarded. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LTcopy_region(const char *file_src, - const char *path_src, - const hsize_t *block_coord_src, - const char *file_dest, - const char *path_dest, - const hsize_t *block_coord_dset); - -/*------------------------------------------------------------------------- - * - * Read dataset functions - * - *------------------------------------------------------------------------- - */ - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Reads selected data to an application buffer. - * - * \param[in] file Name of file - * \param[in] path Full path to a dataset - * \param[in] block_coord Hyperslab coordinates - * \param[in] mem_type Memory datatype, describing the buffer - * the referenced data will be read into - * \param[out] buf Buffer containing data from the - * referenced region - * - * \return \herr_t - * - * \details H5LTread_region() reads data from a region described by - * the hyperslab coordinates in \p block_coord, located in - * the dataset specified by its absolute path \p path in a - * file specified by its name \p file. Data is read into a - * buffer \p buf of the datatype that corresponds to the - * HDF5 datatype specified by \p mem_type. - * - * Buffer \p block_coord has size 2*rank and is the coordinates - * of the starting point following by the coordinates of the - * ending point of the hyperslab. For example, to extract a - * rectangular hyperslab region starting at element (2,2) to - * element (5,4) then \p block_coord would be {2, 2, 5, 4}. - * - * Buffer \p buf should be big enough to hold selected elements - * of the type that corresponds to the \p mem_type - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LTread_region(const char *file, - const char *path, - const hsize_t *block_coord, - hid_t mem_type, - void *buf ); - -/** - * -------------------------------------------------------------------------- - * \ingroup H5LR - * - * \brief Retrieves the values of quality flags for each element - * to the application provided buffer. - * - * \param[in] dset_id Identifier of the dataset with bit-field values - * \param[in] num_values Number of the values to be extracted - * \param[in] offset Array of staring bits to be extracted from - * the element; valid values: 0 (zero) through 7 - * \param[in] lengths Array of the number of bits to be extracted - * for each value - * \param[in] space Dataspace identifier, describing the elements - * to be read from the dataset with bit-field - * values - * \param[out] buf Buffer to read the values in - * - * \return \herr_t - * - * \details H5LTread_bitfield_value() reads selected elements from a - * dataset specified by its identifier \p dset_id, and unpacks - * the bit-field values to a buffer \p buf. - * - * The parameter \p space is a space identifier that indicates - * which elements of the dataset should be read. - * - * The parameter \p offset is an array of length \p num_values; - * the i<sup>th</sup> element of the array holds the value of the - * starting bit of the i<sup>th</sup> bit-field value. - * Valid values are: 0 (zero) through 7. - * - * The parameter \p lengths is an array of length \p num_values; - * the i<sup>th</sup> element of the array holds the number of - * bits to be extracted for the i<sup>th</sup> bit-field value. - * Extracted bits will be interpreted as a base-2 integer value. - * Each value will be converted to the base-10 integer value and - * stored in the application buffer. - * - * Buffer \p buf is allocated by the application and should be big - * enough to hold \c num_sel_elem * \p num_values elements of the - * specified type, where \c num_sel_elem is a number of the elements - * to be read from the dataset. Data in the buffer is organized - * as \p num_values values for the first element, followed by the - * \p num_values values for the second element, ... , followed by - * the \p num_values values for the - * \c num_selected_elem<sup>th</sup> element. - * - * \version 1.1 Fortran wrapper introduced in this release. - * - * \since 1.0 - * - */ -H5_HLRDLL herr_t H5LTread_bitfield_value(hid_t dset_id, int num_values, const unsigned *offset, - const unsigned *lengths, hid_t space, int *buf); - |