summaryrefslogtreecommitdiffstats
path: root/hl/src/H5IMpublic.h
diff options
context:
space:
mode:
authorvchoi-hdfgroup <55293060+vchoi-hdfgroup@users.noreply.github.com>2022-07-01 15:42:15 (GMT)
committerGitHub <noreply@github.com>2022-07-01 15:42:15 (GMT)
commit9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6 (patch)
tree8921d2c772d5616a1251b312663a97f5d0513406 /hl/src/H5IMpublic.h
parent3ed53d17fb018c0415be2d668c6765217deff16f (diff)
downloadhdf5-9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6.zip
hdf5-9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6.tar.gz
hdf5-9e97a22b8bb7cc92f0b2ef2b63de61e9da50aba6.tar.bz2
Add doxygen for high level modules. (#1839)
* Add doxygen for high level modules. * Committing clang-format changes * Correct spelling based on spelling check. * Committing clang-format changes Co-authored-by: vchoi <vchoi@jelly.ad.hdfgroup.org> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'hl/src/H5IMpublic.h')
-rw-r--r--hl/src/H5IMpublic.h293
1 files changed, 293 insertions, 0 deletions
diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h
index 2843942..2129509 100644
--- a/hl/src/H5IMpublic.h
+++ b/hl/src/H5IMpublic.h
@@ -18,33 +18,326 @@
extern "C" {
#endif
+/**\defgroup H5IM Images
+ *
+ * <em>Creating and manipulating HDF5 datasets intended to be
+ * interpreted as images (H5IM)</em>
+ *
+ * The specification for the Images API is presented in another
+ * document: \ref IMG
+ * This version of the API is primarily concerned with two dimensional raster
+ * data similar to HDF4 Raster Images.
+ * The HDF5 Images API uses the \ref H5LT HDF5 API.
+ *
+ * \note \Bold{Programming hints:}
+ * \note To use any of these functions or subroutines,
+ * you must first include the relevant include file (C) or
+ * module (Fortran) in your application.
+ * \note The following line includes the HDF5 Images package, H5IM,
+ * in C applications:
+ * \code #include "hdf5_hl.h" \endcode
+ * \note This line includes the H5IM module in Fortran applications:
+ * \code use h5im \endcode
+ *
+ * - \ref H5IMget_image_info
+ * \n Gets information about an image dataset (dimensions,
+ * interlace mode and number of associated palettes).
+ * - \ref H5IMget_npalettes
+ * \n Gets the number of palettes associated to an image.
+ * - \ref H5IMget_palette
+ * \n Gets the palette dataset.
+ * - \ref H5IMget_palette_info
+ * \n Gets information about a palette dataset (dimensions).
+ * - \ref H5IMis_image
+ * \n Inquires if a dataset is an image
+ * - \ref H5IMis_palette
+ * \n Inquires if a dataset is a palette.
+ * - \ref H5IMlink_palette
+ * \n Attaches a palette to an image.
+ * - \ref H5IMmake_image_8bit
+ * \n Creates and writes an image.
+ * - \ref H5IMmake_image_24bit
+ * \n Creates and writes a true color image.
+ * - \ref H5IMmake_palette
+ * \n Creates and writes a palette.
+ * - \ref H5IMread_image
+ * \n Reads image data from disk.
+ * - \ref H5IMunlink_palette
+ * \n Dettaches a palette from an image.
+ * .
+ *
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Creates and writes an image.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] width The width of the image
+ * \param[in] height The height of the image
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMmake_image_8bit() creates and writes a dataset named
+ * \p dset_name attached to the file or group specified by the
+ * identifier \p loc_id. Attributes conforming to the HDF5 Image
+ * and Palette specification for an indexed image are attached to
+ * the dataset, thus identifying it as an image. The image data is
+ * of the type #H5T_NATIVE_UCHAR. An indexed image is an image in
+ * which each each pixel information storage is an index to a
+ * table palette.
+ *
+ */
H5_HLDLL herr_t H5IMmake_image_8bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height,
const unsigned char *buffer);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Creates and writes a true color image.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[in] width The width of the image
+ * \param[in] height The height of the image
+ * \param[in] interlace String defining the interlace mode
+ * \param[in] buffer Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMmake_image_24bit() creates and writes a dataset named
+ * \p dset_name attached to the file or group specified by the
+ * identifier \p loc_id. This function defines a true color image
+ * conforming to the HDF5 Image and Palette specification.
+ * The function assumes that the image data is of the type
+ * #H5T_NATIVE_UCHAR.
+ *
+ * A true color image is an image where the pixel storage contains
+ * several color planes. In a 24 bit RGB color model, these planes
+ * are red, green and blue. In a true color image the stream of bytes
+ * can be stored in several different ways, thus defining the
+ * interlace (or interleaving) mode. The 2 most used types of interlace mode
+ * are interlace by pixel and interlace by plane. In the 24 bit RGB color
+ * model example, interlace by plane means all the red components for the
+ * entire dataset are stored first, followed by all the green components,
+ * and then by all the blue components. Interlace by pixel in this example
+ * means that for each pixel the sequence red, green, blue is defined.
+ * In this function, the interlace mode is defined in the parameter
+ * \p interlace, a string that can have the values INTERLACE_PIXEL
+ * or INTERLACE_PLANE.
+ *
+ */
H5_HLDLL herr_t H5IMmake_image_24bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height,
const char *interlace, const unsigned char *buffer);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets information about an image dataset
+ * (dimensions, interlace mode and number of associated palettes).
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ * \param[out] width The width of the image
+ * \param[out] height The height of the image
+ * \param[out] planes The number of color planes of the image
+ * \param[out] interlace The interlace mode of the image
+ * \param[out] npals The number of palettes associated to the image
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_image_info() gets information about an image
+ * named \p dset_name attached to the file or group specified
+ * by the identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5IMget_image_info(hid_t loc_id, const char *dset_name, hsize_t *width, hsize_t *height,
hsize_t *planes, char *interlace, hssize_t *npals);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Reads image data from disk.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset to create
+ * \param[out] buffer Buffer with data to store the image
+ *
+ * \return \herr_t
+ *
+ * \details H5IMread_image() reads a dataset named \p dset_name
+ * attached to the file or group specified by the
+ * identifier \p loc_id.
+ *
+ */
H5_HLDLL herr_t H5IMread_image(hid_t loc_id, const char *dset_name, unsigned char *buffer);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Creates and writes a palette.
+ *
+ * \fg_loc_id
+ * \param[in] pal_name The name of the palette
+ * \param[in] pal_dims An array of the size of the palette dimensions
+ * \param[in] pal_data Buffer with data to be written to the dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMmake_palette() creates and writes a dataset
+ * named \p pal_name. Attributes conforming to the HDF5 Image and
+ * Palette specification are attached to the dataset, thus
+ * identifying it as a palette. The palette data is of the
+ * type #H5T_NATIVE_UCHAR.
+ *
+ */
H5_HLDLL herr_t H5IMmake_palette(hid_t loc_id, const char *pal_name, const hsize_t *pal_dims,
const unsigned char *pal_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Attaches a palette to an image.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the dataset to attach the palette to
+ * \param[in] pal_name The name of the palette
+ *
+ * \return \herr_t
+ *
+ * \details H5IMlink_palette() attaches a palette named \p pal_name
+ * to an image specified by \p image_name. The image dataset
+ * may or not already have an attached palette. If it has,
+ * the array of palette references is extended to hold the reference
+ * to the new palette.
+ *
+ */
H5_HLDLL herr_t H5IMlink_palette(hid_t loc_id, const char *image_name, const char *pal_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Dettaches a palette from an image.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[in] pal_name The name of the palette
+ *
+ * \return \herr_t
+ *
+ * \details H5IMunlink_palette() dettaches a palette from an image
+ * specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMunlink_palette(hid_t loc_id, const char *image_name, const char *pal_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets the number of palettes associated to an image.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[out] npals The number of palettes
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_npalettes() gets the number of palettes associated to
+ * an image specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMget_npalettes(hid_t loc_id, const char *image_name, hssize_t *npals);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets information about a palette dataset (dimensions).
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[in] pal_number The zero based index that identifies
+ * the palette
+ * \param[out] pal_dims The dimensions of the palette dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_palette_info() gets the dimensions of the palette
+ * dataset identified by \p pal_number (a zero based index)
+ * associated to an image specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMget_palette_info(hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Gets the palette dataset.
+ *
+ * \fg_loc_id
+ * \param[in] image_name The name of the image dataset
+ * \param[in] pal_number The zero based index that identifies
+ * the palette
+ * \param[out] pal_data The palette dataset
+ *
+ * \return \herr_t
+ *
+ * \details H5IMget_palette() gets the palette dataset identified
+ * by \p pal_number (a zero based index) associated to an
+ * image specified by \p image_name.
+ *
+ */
H5_HLDLL herr_t H5IMget_palette(hid_t loc_id, const char *image_name, int pal_number,
unsigned char *pal_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Inquires if a dataset is an image.
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ *
+ * \return \htri_t
+ *
+ * \details H5IMis_image() inquires if a dataset named \p dset_name,
+ * attached to the file or group specified by the identifier
+ * \p loc_id, is an image based on the HDF5 Image and Palette
+ * Specification.
+ *
+ */
H5_HLDLL herr_t H5IMis_image(hid_t loc_id, const char *dset_name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5IM
+ *
+ * \brief Inquires if a dataset is a palette
+ *
+ * \fg_loc_id
+ * \param[in] dset_name The name of the dataset
+ *
+ * \return \htri_t
+ *
+ * \details H5IMis_palette() inquires if a dataset named \p dset_name,
+ * attached to the file or group specified by the
+ * identifier \p loc_id, is a palette based on the HDF5
+ * Image and Palette Specification.
+ *
+ */
H5_HLDLL herr_t H5IMis_palette(hid_t loc_id, const char *dset_name);
#ifdef __cplusplus