1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the COPYING file, which can be found at the root of the source code * 9 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * 10 * If you do not have access to either file, you may request a copy from * 11 * help@hdfgroup.org. * 12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 13 14 /* 15 * Programmer: Quincey Koziol <koziol@ncsa.uiuc.edu> 16 * Thursday, September 28, 2000 17 * 18 * Purpose: This file contains declarations which are visible only within 19 * the H5S package. Source files outside the H5S package should 20 * include H5Sprivate.h instead. 21 */ 22 #if !(defined H5S_FRIEND || defined H5S_MODULE) 23 #error "Do not include this file outside the H5S package!" 24 #endif 25 26 #ifndef _H5Spkg_H 27 #define _H5Spkg_H 28 29 #include "H5Sprivate.h" 30 31 /* Flags to indicate special dataspace features are active */ 32 #define H5S_VALID_MAX 0x01 33 #define H5S_VALID_PERM 0x02 34 35 /* Flags for serialization of selections */ 36 #define H5S_HYPER_REGULAR 0x01 37 #define H5S_SELECT_FLAG_BITS (H5S_HYPER_REGULAR) 38 39 /* Versions for H5S_SEL_HYPER selection info */ 40 #define H5S_HYPER_VERSION_1 1 41 #define H5S_HYPER_VERSION_2 2 42 43 /* Versions for H5S_SEL_POINTS selection info */ 44 #define H5S_POINT_VERSION_1 1 45 46 /* Versions for H5S_SEL_NONE selection info */ 47 #define H5S_NONE_VERSION_1 1 48 49 /* Versions for H5S_SEL_ALL selection info */ 50 #define H5S_ALL_VERSION_1 1 51 52 /* Size of point/offset info for H5S_SEL_POINTS/H5S_SEL_HYPER */ 53 #define H5S_INFO_SIZE_4 0x04 /* 4 bytes: 32 bits */ 54 #define H5S_INFO_SIZE_8 0x08 /* 8 bytes: 64 bits */ 55 #define H5S_SELECT_INFO_SIZE_BITS (H5S_INFO_SIZE_4|H5S_INFO_SIZE_8) 56 57 #define H5S_UINT32_MAX 4294967295 /* 2^32 - 1 */ 58 59 /* Length of stack-allocated sequences for "project intersect" routines */ 60 #define H5S_PROJECT_INTERSECT_NSEQS 256 61 62 63 /* Initial version of the dataspace information */ 64 #define H5O_SDSPACE_VERSION_1 1 65 66 /* This version adds support for "null" dataspaces, encodes the type of the 67 * dataspace in the message and eliminated the rest of the "reserved" 68 * bytes. 69 */ 70 #define H5O_SDSPACE_VERSION_2 2 71 72 /* The latest version of the format. Look through the 'encode' 73 * and 'size' callbacks for places to change when updating this. */ 74 #define H5O_SDSPACE_VERSION_LATEST H5O_SDSPACE_VERSION_2 75 76 /* Maximum dimension size (highest value that is not a special value e.g. 77 * H5S_UNLIMITED) */ 78 #define H5S_MAX_SIZE ((hsize_t)(hssize_t)(-2)) 79 80 81 /* 82 * Dataspace extent information 83 */ 84 /* Extent container */ 85 struct H5S_extent_t { 86 H5O_shared_t sh_loc; /* Shared message info (must be first) */ 87 88 H5S_class_t type; /* Type of extent */ 89 unsigned version; /* Version of object header message to encode this object with */ 90 hsize_t nelem; /* Number of elements in extent */ 91 92 unsigned rank; /* Number of dimensions */ 93 hsize_t *size; /* Current size of the dimensions */ 94 hsize_t *max; /* Maximum size of the dimensions */ 95 }; 96 97 /* 98 * Dataspace selection information 99 */ 100 /* Node in point selection list (typedef'd in H5Sprivate.h) */ 101 struct H5S_pnt_node_t { 102 hsize_t *pnt; /* Pointer to a selected point */ 103 struct H5S_pnt_node_t *next; /* pointer to next point in list */ 104 }; 105 106 /* Information about point selection list */ 107 typedef struct { 108 H5S_pnt_node_t *head; /* Pointer to head of point list */ 109 } H5S_pnt_list_t; 110 111 /* Information about new-style hyperslab spans */ 112 113 /* Information a particular hyperslab span */ 114 struct H5S_hyper_span_t { 115 hsize_t low, high; /* Low & high bounds of span */ 116 hsize_t nelem; /* Number of elements in span (only needed during I/O) */ 117 hsize_t pstride; /* Pseudo-stride from start of previous span (only used during I/O) */ 118 struct H5S_hyper_span_info_t *down; /* Pointer to list of spans in next dimension down */ 119 struct H5S_hyper_span_t *next; /* Pointer to next span in list */ 120 }; 121 122 /* Information about a list of hyperslab spans in one dimension */ 123 struct H5S_hyper_span_info_t { 124 unsigned count; /* Ref. count of number of spans which share this span */ 125 struct H5S_hyper_span_info_t *scratch; /* Scratch pointer 126 * (used during copies, as mark 127 * during precomputes for I/O & 128 * to point to the last span in a 129 * list during single element adds) 130 */ 131 struct H5S_hyper_span_t *head; /* Pointer to list of spans in next dimension down */ 132 }; 133 134 /* Information about new-style hyperslab selection */ 135 typedef struct { 136 hbool_t diminfo_valid; /* Whether the dataset has valid diminfo */ 137 H5S_hyper_dim_t opt_diminfo[H5S_MAX_RANK]; /* per-dim selection info */ 138 H5S_hyper_dim_t app_diminfo[H5S_MAX_RANK]; /* per-dim selection info */ 139 /* 'opt_diminfo' points to a [potentially] optimized version of the user's 140 * hyperslab information. 'app_diminfo' points to the actual parameters 141 * that the application used for setting the hyperslab selection. These 142 * are only used for re-gurgitating the original values used to set the 143 * hyperslab to the application when it queries the hyperslab selection 144 * information. */ 145 int unlim_dim; /* Dimension where selection is unlimited, or -1 if none */ 146 hsize_t num_elem_non_unlim; /* # of elements in a "slice" excluding the unlimited dimension */ 147 H5S_hyper_span_info_t *span_lst; /* List of hyperslab span information */ 148 } H5S_hyper_sel_t; 149 150 /* Selection information methods */ 151 /* Method to copy a selection */ 152 typedef herr_t (*H5S_sel_copy_func_t)(H5S_t *dst, const H5S_t *src, hbool_t share_selection); 153 /* Method to retrieve a list of offset/length sequences for selection */ 154 typedef herr_t (*H5S_sel_get_seq_list_func_t)(const H5S_t *space, unsigned flags, 155 H5S_sel_iter_t *iter, size_t maxseq, size_t maxbytes, 156 size_t *nseq, size_t *nbytes, hsize_t *off, size_t *len); 157 /* Method to release current selection */ 158 typedef herr_t (*H5S_sel_release_func_t)(H5S_t *space); 159 /* Method to determine if current selection is valid for dataspace */ 160 typedef htri_t (*H5S_sel_is_valid_func_t)(const H5S_t *space); 161 /* Method to determine number of bytes required to store current selection */ 162 typedef hssize_t (*H5S_sel_serial_size_func_t)(const H5S_t *space, H5F_t *f); 163 /* Method to store current selection in "serialized" form (a byte sequence suitable for storing on disk) */ 164 typedef herr_t (*H5S_sel_serialize_func_t)(const H5S_t *space, uint8_t **p, H5F_t *f); 165 /* Method to create selection from "serialized" form (a byte sequence suitable for storing on disk) */ 166 typedef herr_t (*H5S_sel_deserialize_func_t)(H5S_t *space, uint32_t version, uint8_t flags, 167 const uint8_t **p); 168 /* Method to determine smallest n-D bounding box containing the current selection */ 169 typedef herr_t (*H5S_sel_bounds_func_t)(const H5S_t *space, hsize_t *start, hsize_t *end); 170 /* Method to determine linear offset of initial element in selection within dataspace */ 171 typedef herr_t (*H5S_sel_offset_func_t)(const H5S_t *space, hsize_t *offset); 172 /* Method to get unlimited dimension of selection (or -1 for none) */ 173 typedef int (*H5S_sel_unlim_dim_func_t)(const H5S_t *space); 174 /* Method to get the number of elements in a slice through the unlimited dimension */ 175 typedef herr_t (*H5S_sel_num_elem_non_unlim_func_t)(const H5S_t *space, 176 hsize_t *num_elem_non_unlim); 177 /* Method to determine if current selection is contiguous */ 178 typedef htri_t (*H5S_sel_is_contiguous_func_t)(const H5S_t *space); 179 /* Method to determine if current selection is a single block */ 180 typedef htri_t (*H5S_sel_is_single_func_t)(const H5S_t *space); 181 /* Method to determine if current selection is "regular" */ 182 typedef htri_t (*H5S_sel_is_regular_func_t)(const H5S_t *space); 183 /* Method to adjust a selection by an offset */ 184 typedef void (*H5S_sel_adjust_u_func_t)(H5S_t *space, const hsize_t *offset); 185 /* Method to construct single element projection onto scalar dataspace */ 186 typedef herr_t (*H5S_sel_project_scalar)(const H5S_t *space, hsize_t *offset); 187 /* Method to construct selection projection onto/into simple dataspace */ 188 typedef herr_t (*H5S_sel_project_simple)(const H5S_t *space, H5S_t *new_space, hsize_t *offset); 189 /* Method to initialize iterator for current selection */ 190 typedef herr_t (*H5S_sel_iter_init_func_t)(H5S_sel_iter_t *sel_iter, const H5S_t *space); 191 192 /* Selection class information */ 193 typedef struct { 194 H5S_sel_type type; /* Type of selection (all, none, points or hyperslab) */ 195 196 /* Methods */ 197 H5S_sel_copy_func_t copy; /* Method to make a copy of a selection */ 198 H5S_sel_get_seq_list_func_t get_seq_list; /* Method to retrieve a list of offset/length sequences for selection */ 199 H5S_sel_release_func_t release; /* Method to release current selection */ 200 H5S_sel_is_valid_func_t is_valid; /* Method to determine if current selection is valid for dataspace */ 201 H5S_sel_serial_size_func_t serial_size; /* Method to determine number of bytes required to store current selection */ 202 H5S_sel_serialize_func_t serialize; /* Method to store current selection in "serialized" form (a byte sequence suitable for storing on disk) */ 203 H5S_sel_deserialize_func_t deserialize; /* Method to store create selection from "serialized" form (a byte sequence suitable for storing on disk) */ 204 H5S_sel_bounds_func_t bounds; /* Method to determine to smallest n-D bounding box containing the current selection */ 205 H5S_sel_offset_func_t offset; /* Method to determine linear offset of initial element in selection within dataspace */ 206 H5S_sel_unlim_dim_func_t unlim_dim; /* Method to get unlimited dimension of selection (or -1 for none) */ 207 H5S_sel_num_elem_non_unlim_func_t num_elem_non_unlim; /* Method to get the number of elements in a slice through the unlimited dimension */ 208 H5S_sel_is_contiguous_func_t is_contiguous; /* Method to determine if current selection is contiguous */ 209 H5S_sel_is_single_func_t is_single; /* Method to determine if current selection is a single block */ 210 H5S_sel_is_regular_func_t is_regular; /* Method to determine if current selection is "regular" */ 211 H5S_sel_adjust_u_func_t adjust_u; /* Method to adjust a selection by an offset */ 212 H5S_sel_project_scalar project_scalar; /* Method to construct scalar dataspace projection */ 213 H5S_sel_project_simple project_simple; /* Method to construct simple dataspace projection */ 214 H5S_sel_iter_init_func_t iter_init; /* Method to initialize iterator for current selection */ 215 } H5S_select_class_t; 216 217 /* Selection information object */ 218 typedef struct { 219 const H5S_select_class_t *type; /* Pointer to selection's class info */ 220 221 hbool_t offset_changed; /* Indicate that the offset for the selection has been changed */ 222 hssize_t offset[H5S_MAX_RANK]; /* Offset within the extent */ 223 224 hsize_t num_elem; /* Number of elements in selection */ 225 226 union { 227 H5S_pnt_list_t *pnt_lst; /* Info about list of selected points (order is important) */ 228 H5S_hyper_sel_t *hslab; /* Info about hyperslab selection */ 229 } sel_info; 230 } H5S_select_t; 231 232 /* Main dataspace structure (typedef'd in H5Sprivate.h) */ 233 struct H5S_t { 234 H5S_extent_t extent; /* Dataspace extent (must stay first) */ 235 H5S_select_t select; /* Dataspace selection */ 236 }; 237 238 /* Selection iteration methods */ 239 /* Method to retrieve the current coordinates of iterator for current selection */ 240 typedef herr_t (*H5S_sel_iter_coords_func_t)(const H5S_sel_iter_t *iter, hsize_t *coords); 241 /* Method to retrieve the current block of iterator for current selection */ 242 typedef herr_t (*H5S_sel_iter_block_func_t)(const H5S_sel_iter_t *iter, hsize_t *start, hsize_t *end); 243 /* Method to determine number of elements left in iterator for current selection */ 244 typedef hsize_t (*H5S_sel_iter_nelmts_func_t)(const H5S_sel_iter_t *iter); 245 /* Method to determine if there are more blocks left in the current selection */ 246 typedef htri_t (*H5S_sel_iter_has_next_block_func_t)(const H5S_sel_iter_t *iter); 247 /* Method to move selection iterator to the next element in the selection */ 248 typedef herr_t (*H5S_sel_iter_next_func_t)(H5S_sel_iter_t *iter, hsize_t nelem); 249 /* Method to move selection iterator to the next block in the selection */ 250 typedef herr_t (*H5S_sel_iter_next_block_func_t)(H5S_sel_iter_t *iter); 251 /* Method to release iterator for current selection */ 252 typedef herr_t (*H5S_sel_iter_release_func_t)(H5S_sel_iter_t *iter); 253 254 /* Selection iteration class */ 255 typedef struct H5S_sel_iter_class_t { 256 H5S_sel_type type; /* Type of selection (all, none, points or hyperslab) */ 257 258 /* Methods on selections */ 259 H5S_sel_iter_coords_func_t iter_coords; /* Method to retrieve the current coordinates of iterator for current selection */ 260 H5S_sel_iter_block_func_t iter_block; /* Method to retrieve the current block of iterator for current selection */ 261 H5S_sel_iter_nelmts_func_t iter_nelmts; /* Method to determine number of elements left in iterator for current selection */ 262 H5S_sel_iter_has_next_block_func_t iter_has_next_block; /* Method to query if there is another block left in the selection */ 263 H5S_sel_iter_next_func_t iter_next; /* Method to move selection iterator to the next element in the selection */ 264 H5S_sel_iter_next_block_func_t iter_next_block; /* Method to move selection iterator to the next block in the selection */ 265 H5S_sel_iter_release_func_t iter_release; /* Method to release iterator for current selection */ 266 } H5S_sel_iter_class_t; 267 268 /* 269 * All selection class methods. 270 */ 271 H5_DLLVAR const H5S_select_class_t H5S_sel_all[1]; 272 273 /* 274 * Hyperslab selection class methods. 275 */ 276 H5_DLLVAR const H5S_select_class_t H5S_sel_hyper[1]; 277 278 /* 279 * None selection class methods. 280 */ 281 H5_DLLVAR const H5S_select_class_t H5S_sel_none[1]; 282 283 /* 284 * Pointer selection class methods. 285 */ 286 H5_DLLVAR const H5S_select_class_t H5S_sel_point[1]; 287 288 /* Array of versions for Dataspace and hyperslab selections */ 289 H5_DLLVAR const unsigned H5O_sdspace_ver_bounds[H5F_LIBVER_NBOUNDS]; 290 H5_DLLVAR const unsigned H5O_sds_hyper_ver_bounds[H5F_LIBVER_NBOUNDS]; 291 292 /* Extent functions */ 293 H5_DLL herr_t H5S_extent_release(H5S_extent_t *extent); 294 H5_DLL herr_t H5S_extent_copy_real(H5S_extent_t *dst, const H5S_extent_t *src, 295 hbool_t copy_max); 296 297 /* Operations on selections */ 298 H5_DLL herr_t H5S__hyper_project_intersection(const H5S_t *src_space, 299 const H5S_t *dst_space, const H5S_t *src_intersect_space, 300 H5S_t *proj_space); 301 H5_DLL herr_t H5S__hyper_subtract(H5S_t *space, H5S_t *subtract_space); 302 303 /* Testing functions */ 304 #ifdef H5S_TESTING 305 H5_DLL htri_t H5S_select_shape_same_test(hid_t sid1, hid_t sid2); 306 H5_DLL htri_t H5S_get_rebuild_status_test(hid_t space_id); 307 #endif /* H5S_TESTING */ 308 309 #endif /*_H5Spkg_H*/ 310 311