H5Spkg.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * Programmer:  Quincey Koziol <koziol@ncsa.uiuc.edu>
00018  *              Thursday, September 28, 2000
00019  *
00020  * Purpose:     This file contains declarations which are visible only within
00021  *              the H5S package.  Source files outside the H5S package should
00022  *              include H5Sprivate.h instead.
00023  */
00024 #ifndef H5S_PACKAGE
00025 #error "Do not include this file outside the H5S package!"
00026 #endif
00027 
00028 #ifndef _H5Spkg_H
00029 #define _H5Spkg_H
00030 
00031 #include "H5Sprivate.h"
00032 
00033 /* Flags to indicate special dataspace features are active */
00034 #define H5S_VALID_MAX   0x01
00035 #define H5S_VALID_PERM  0x02
00036 
00037 
00038 /* Initial version of the dataspace information */
00039 #define H5O_SDSPACE_VERSION_1   1
00040 
00041 /* This version adds support for "null" dataspaces, encodes the type of the
00042  *      dataspace in the message and eliminated the rest of the "reserved"
00043  *      bytes.
00044  */
00045 #define H5O_SDSPACE_VERSION_2   2
00046 
00047 /* The latest version of the format.  Look through the 'encode'
00048  *      and 'size' callbacks for places to change when updating this. */
00049 #define H5O_SDSPACE_VERSION_LATEST H5O_SDSPACE_VERSION_2
00050 
00051 
00052 /*
00053  * Dataspace extent information
00054  */
00055 /* Extent container */
00056 struct H5S_extent_t {
00057     H5O_shared_t sh_loc;        /* Shared message info (must be first) */
00058 
00059     H5S_class_t type;           /* Type of extent */
00060     unsigned version;           /* Version of object header message to encode this object with */
00061     hsize_t nelem;              /* Number of elements in extent */
00062 
00063     unsigned rank;              /* Number of dimensions */
00064     hsize_t *size;              /* Current size of the dimensions */
00065     hsize_t *max;               /* Maximum size of the dimensions */
00066 };
00067 
00068 /*
00069  * Dataspace selection information
00070  */
00071 /* Node in point selection list (typedef'd in H5Sprivate.h) */
00072 struct H5S_pnt_node_t {
00073     hsize_t *pnt;          /* Pointer to a selected point */
00074     struct H5S_pnt_node_t *next;  /* pointer to next point in list */
00075 };
00076 
00077 /* Information about point selection list */
00078 typedef struct {
00079     H5S_pnt_node_t *head;   /* Pointer to head of point list */
00080 } H5S_pnt_list_t;
00081 
00082 /* Information about new-style hyperslab spans */
00083 
00084 /* Information a particular hyperslab span */
00085 struct H5S_hyper_span_t {
00086     hsize_t low, high;          /* Low & high bounds of span */
00087     hsize_t nelem;              /* Number of elements in span (only needed during I/O) */
00088     hsize_t pstride;            /* Pseudo-stride from start of previous span (only used during I/O) */
00089     struct H5S_hyper_span_info_t *down;     /* Pointer to list of spans in next dimension down */
00090     struct H5S_hyper_span_t *next;     /* Pointer to next span in list */
00091 };
00092 
00093 /* Information about a list of hyperslab spans */
00094 struct H5S_hyper_span_info_t {
00095     unsigned count;                    /* Ref. count of number of spans which share this span */
00096     struct H5S_hyper_span_info_t *scratch;  /* Scratch pointer
00097                                              * (used during copies, as mark
00098                                              * during precomputes for I/O &
00099                                              * to point to the last span in a
00100                                              * list during single element adds)
00101                                              */
00102     struct H5S_hyper_span_t *head;  /* Pointer to list of spans in next dimension down */
00103 };
00104 
00105 /* Information about new-style hyperslab selection */
00106 typedef struct {
00107     hbool_t diminfo_valid;                      /* Whether the dataset has valid diminfo */
00108     H5S_hyper_dim_t opt_diminfo[H5S_MAX_RANK];  /* per-dim selection info */
00109     H5S_hyper_dim_t app_diminfo[H5S_MAX_RANK];  /* per-dim selection info */
00110         /* 'opt_diminfo' points to a [potentially] optimized version of the user's
00111          * hyperslab information.  'app_diminfo' points to the actual parameters
00112          * that the application used for setting the hyperslab selection.  These
00113          * are only used for re-gurgitating the original values used to set the
00114          * hyperslab to the application when it queries the hyperslab selection
00115          * information. */
00116     H5S_hyper_span_info_t *span_lst; /* List of hyperslab span information */
00117 } H5S_hyper_sel_t;
00118 
00119 /* Selection information methods */
00120 /* Method to copy a selection */
00121 typedef herr_t (*H5S_sel_copy_func_t)(H5S_t *dst, const H5S_t *src, hbool_t share_selection);
00122 /* Method to retrieve a list of offset/length sequences for selection */
00123 typedef herr_t (*H5S_sel_get_seq_list_func_t)(const H5S_t *space, unsigned flags,
00124     H5S_sel_iter_t *iter, size_t maxseq, size_t maxbytes,
00125     size_t *nseq, size_t *nbytes, hsize_t *off, size_t *len);
00126 /* Method to release current selection */
00127 typedef herr_t (*H5S_sel_release_func_t)(H5S_t *space);
00128 /* Method to determine if current selection is valid for dataspace */
00129 typedef htri_t (*H5S_sel_is_valid_func_t)(const H5S_t *space);
00130 /* Method to determine number of bytes required to store current selection */
00131 typedef hssize_t (*H5S_sel_serial_size_func_t)(const H5S_t *space);
00132 /* Method to store current selection in "serialized" form (a byte sequence suitable for storing on disk) */
00133 typedef herr_t (*H5S_sel_serialize_func_t)(const H5S_t *space, uint8_t *buf);
00134 /* Method to store create selection from "serialized" form (a byte sequence suitable for storing on disk) */
00135 typedef herr_t (*H5S_sel_deserialize_func_t)(H5S_t *space, const uint8_t *buf);
00136 /* Method to determine smallest n-D bounding box containing the current selection */
00137 typedef herr_t (*H5S_sel_bounds_func_t)(const H5S_t *space, hsize_t *start, hsize_t *end);
00138 /* Method to determine linear offset of initial element in selection within dataspace */
00139 typedef herr_t (*H5S_sel_offset_func_t)(const H5S_t *space, hsize_t *offset);
00140 /* Method to determine if current selection is contiguous */
00141 typedef htri_t (*H5S_sel_is_contiguous_func_t)(const H5S_t *space);
00142 /* Method to determine if current selection is a single block */
00143 typedef htri_t (*H5S_sel_is_single_func_t)(const H5S_t *space);
00144 /* Method to determine if current selection is "regular" */
00145 typedef htri_t (*H5S_sel_is_regular_func_t)(const H5S_t *space);
00146 /* Method to adjust a selection by an offset */
00147 typedef herr_t (*H5S_sel_adjust_u_func_t)(H5S_t *space, const hsize_t *offset);
00148 /* Method to initialize iterator for current selection */
00149 typedef herr_t (*H5S_sel_iter_init_func_t)(H5S_sel_iter_t *sel_iter, const H5S_t *space);
00150 
00151 /* Selection class information */
00152 typedef struct {
00153     H5S_sel_type type;                          /* Type of selection (all, none, points or hyperslab) */
00154 
00155     /* Methods */
00156     H5S_sel_copy_func_t copy;                   /* Method to make a copy of a selection */
00157     H5S_sel_get_seq_list_func_t get_seq_list;   /* Method to retrieve a list of offset/length sequences for selection */
00158     H5S_sel_release_func_t release;             /* Method to release current selection */
00159     H5S_sel_is_valid_func_t is_valid;           /* Method to determine if current selection is valid for dataspace */
00160     H5S_sel_serial_size_func_t serial_size;     /* Method to determine number of bytes required to store current selection */
00161     H5S_sel_serialize_func_t serialize;         /* Method to store current selection in "serialized" form (a byte sequence suitable for storing on disk) */
00162     H5S_sel_deserialize_func_t deserialize;     /* Method to store create selection from "serialized" form (a byte sequence suitable for storing on disk) */
00163     H5S_sel_bounds_func_t bounds;               /* Method to determine to smallest n-D bounding box containing the current selection */
00164     H5S_sel_offset_func_t offset;               /* Method to determine linear offset of initial element in selection within dataspace */
00165     H5S_sel_is_contiguous_func_t is_contiguous; /* Method to determine if current selection is contiguous */
00166     H5S_sel_is_single_func_t is_single;         /* Method to determine if current selection is a single block */
00167     H5S_sel_is_regular_func_t is_regular;       /* Method to determine if current selection is "regular" */
00168     H5S_sel_adjust_u_func_t adjust_u;           /* Method to adjust a selection by an offset */
00169     H5S_sel_iter_init_func_t iter_init;         /* Method to initialize iterator for current selection */
00170 } H5S_select_class_t;
00171 
00172 /* Selection information object */
00173 typedef struct {
00174     const H5S_select_class_t *type;     /* Pointer to selection's class info */
00175     hbool_t offset_changed;             /* Indicate that the offset for the selection has been changed */
00176     hssize_t offset[H5S_MAX_RANK];      /* Offset within the extent */
00177     hsize_t num_elem;   /* Number of elements in selection */
00178     union {
00179         H5S_pnt_list_t *pnt_lst; /* List of selected points (order is important) */
00180         H5S_hyper_sel_t *hslab;  /* Info about hyperslab selections */
00181     } sel_info;
00182 } H5S_select_t;
00183 
00184 /* Main dataspace structure (typedef'd in H5Sprivate.h) */
00185 struct H5S_t {
00186     H5S_extent_t extent;                /* Dataspace extent (must stay first) */
00187     H5S_select_t select;                /* Dataspace selection */
00188 };
00189 
00190 /* Selection iteration methods */
00191 /* Method to retrieve the current coordinates of iterator for current selection */
00192 typedef herr_t (*H5S_sel_iter_coords_func_t)(const H5S_sel_iter_t *iter, hsize_t *coords);
00193 /* Method to retrieve the current block of iterator for current selection */
00194 typedef herr_t (*H5S_sel_iter_block_func_t)(const H5S_sel_iter_t *iter, hsize_t *start, hsize_t *end);
00195 /* Method to determine number of elements left in iterator for current selection */
00196 typedef hsize_t (*H5S_sel_iter_nelmts_func_t)(const H5S_sel_iter_t *iter);
00197 /* Method to determine if there are more blocks left in the current selection */
00198 typedef htri_t (*H5S_sel_iter_has_next_block_func_t)(const H5S_sel_iter_t *iter);
00199 /* Method to move selection iterator to the next element in the selection */
00200 typedef herr_t (*H5S_sel_iter_next_func_t)(H5S_sel_iter_t *iter, size_t nelem);
00201 /* Method to move selection iterator to the next block in the selection */
00202 typedef herr_t (*H5S_sel_iter_next_block_func_t)(H5S_sel_iter_t *iter);
00203 /* Method to release iterator for current selection */
00204 typedef herr_t (*H5S_sel_iter_release_func_t)(H5S_sel_iter_t *iter);
00205 
00206 /* Selection iteration class */
00207 typedef struct H5S_sel_iter_class_t {
00208     H5S_sel_type type;                          /* Type of selection (all, none, points or hyperslab) */
00209 
00210     /* Methods on selections */
00211     H5S_sel_iter_coords_func_t iter_coords;     /* Method to retrieve the current coordinates of iterator for current selection */
00212     H5S_sel_iter_block_func_t iter_block;       /* Method to retrieve the current block of iterator for current selection */
00213     H5S_sel_iter_nelmts_func_t iter_nelmts;     /* Method to determine number of elements left in iterator for current selection */
00214     H5S_sel_iter_has_next_block_func_t iter_has_next_block;         /* Method to query if there is another block left in the selection */
00215     H5S_sel_iter_next_func_t iter_next;         /* Method to move selection iterator to the next element in the selection */
00216     H5S_sel_iter_next_block_func_t iter_next_block;     /* Method to move selection iterator to the next block in the selection */
00217     H5S_sel_iter_release_func_t iter_release;   /* Method to release iterator for current selection */
00218 } H5S_sel_iter_class_t;
00219 
00220 /*
00221  * All selection class methods.
00222  */
00223 H5_DLLVAR const H5S_select_class_t H5S_sel_all[1];
00224 
00225 /*
00226  * Hyperslab selection class methods.
00227  */
00228 H5_DLLVAR const H5S_select_class_t H5S_sel_hyper[1];
00229 
00230 /*
00231  * None selection class methods.
00232  */
00233 H5_DLLVAR const H5S_select_class_t H5S_sel_none[1];
00234 
00235 /*
00236  * Pointer selection class methods.
00237  */
00238 H5_DLLVAR const H5S_select_class_t H5S_sel_point[1];
00239 
00240 /* Extent functions */
00241 H5_DLL herr_t H5S_extent_release(H5S_extent_t *extent);
00242 H5_DLL herr_t H5S_extent_copy(H5S_extent_t *dst, const H5S_extent_t *src,
00243     hbool_t copy_max);
00244 
00245 /* Operations on selections */
00246 
00247 /* Testing functions */
00248 #ifdef H5S_TESTING
00249 H5_DLL htri_t H5S_select_shape_same_test(hid_t sid1, hid_t sid2);
00250 H5_DLL htri_t H5S_get_rebuild_status_test(hid_t space_id);
00251 #endif /* H5S_TESTING */
00252 
00253 #endif /*_H5Spkg_H*/
00254