MOAB: Mesh Oriented datABase
(version 5.3.1)
|
00001 /** 00002 * MOAB, a Mesh-Oriented datABase, is a software component for creating, 00003 * storing and accessing finite element mesh data. 00004 * 00005 * Copyright 2004 Sandia Corporation. Under the terms of Contract 00006 * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government 00007 * retains certain rights in this software. 00008 * 00009 * This library is free software; you can redistribute it and/or 00010 * modify it under the terms of the GNU Lesser General Public 00011 * License as published by the Free Software Foundation; either 00012 * version 2.1 of the License, or (at your option) any later version. 00013 * 00014 */ 00015 00016 #ifndef MHDF_H 00017 #define MHDF_H 00018 00019 #include "moab/mhdf_public.h" 00020 00021 #ifdef __cplusplus 00022 extern "C" { 00023 #endif 00024 00025 /** \page h5mmain H5M File Format API 00026 * 00027 *\section Intro Introduction 00028 * 00029 * MOAB's native file format is based on the HDF5 file format. 00030 * The most common file extension used for such files is .h5m. 00031 * A .h5m file can be identified by the top-level \c tstt group 00032 * in the HDF5 file. 00033 * 00034 * The API implemented by this library is a wrapper on top of the 00035 * underlying HDF5 library. It provides the following features: 00036 * - Enforces and hides MOAB's expected file layout 00037 * - Provides a slightly higher-level API 00038 * - Provides some backwards compatibility for file layout changes 00039 * 00040 * 00041 *\section Overview H5M File Layout 00042 * 00043 * The H5M file format relies on the use of a unique entity ID space for 00044 * all vertices, elements, and entity sets stored in the file. This 00045 * ID space is defined by the application. IDs must be unique over all 00046 * entity types (a vertex and an entity set may not have the same ID.) 00047 * The IDs must be positive (non-zero) integer values. 00048 * There are no other requirements imposed by the format on the ID space. 00049 * 00050 * Elements, with the exception of polyhedra, are defined by a list of 00051 * vertex IDs. Polyhedra are defined by a list of face IDs. Entity sets 00052 * have a list of contained entity IDs, and lists of parent and child 00053 * entity set IDs. The set contents may include any valid entity ID, 00054 * including other sets. The parent and child lists are expected to 00055 * contain only entity IDs corresponding to other entity sets. A zero 00056 * entity ID may be used in some contexts (tag data with the mhdf_ENTITY_ID 00057 * property) to indicate a 'null' value, 00058 * 00059 * Element types are defined by the combination of a topology identifier (e.g. 00060 * hexahedral topology) and the number of nodes in the element. 00061 * 00062 * 00063 *\section Root The tstt Group 00064 * 00065 * All file data is stored in the \c tstt group in the HDF5 root group. 00066 * The \c tstt group may have an optional scalar integer attribute 00067 * named \c max_id . This attribute, if present, should contain the 00068 * value of the largest entity ID used internally to the file. It can 00069 * be used to verify that the code reading the file is using an integer 00070 * type of sufficient size to accommodate the entity IDs. 00071 * 00072 * The \c tstt group contains four sub-groups, a datatype object, and a 00073 * dataset object. The four sub-groups are: \c nodes, \c elements, 00074 * \c sets, and \c tags. The dataset is named \c history . 00075 * 00076 * The \c elemtypes datatype is an enumeration of the elem topologies 00077 * used in the file. The element topologies understood by MOAB are: 00078 * - \c Edge 00079 * - \c Tri 00080 * - \c Quad 00081 * - \c Polygon 00082 * - \c Tet 00083 * - \c Pyramid 00084 * - \c Prism 00085 * - \c Knife 00086 * - \c Hex 00087 * - \c Polyhedron 00088 * 00089 * 00090 *\section History The history DataSet 00091 * 00092 * The \c history DataSet is a list of variable-length strings with 00093 * application-defined meaning. 00094 * 00095 *\section Nodes The nodes Group 00096 * 00097 * 00098 * The \c nodes group contains a single DataSet and an optional 00099 * subgroup. The \c tags subgroup is described in the 00100 * \ref Dense "section on dense tag storage". 00101 * 00102 * The \c coordinates 00103 * DataSet contains the coordinates of all vertices in the mesh. 00104 * The DataSet should contain floating point values and have a dimensions 00105 * \f$ n \times d \f$, where \c n is the number of vertices and \c d 00106 * is the number of coordinate values for each vertex. 00107 * 00108 * The \c coordinates DataSet must have an integer attribute named \c start_id . 00109 * The vertices are then defined to have IDs beginning with this value 00110 * and increasing sequentially in the order that they are defined in the 00111 * \c coordinates table. 00112 * 00113 * 00114 *\section Elements The elements Group 00115 * 00116 * The \c elements group contains an application-defined number of 00117 * subgroups. Each subgroup defines one or more mesh elements that 00118 * have the same topology and length of connectivity (number of nodes 00119 * for any topology other than \c Polyhedron.) The names of the subgroups 00120 * are application defined. MOAB uses a combination of the element 00121 * topology name and connectivity length (e.g. "Hex8".). 00122 * 00123 * Each subgroup must have an attribute named \c element_type that 00124 * contains one of the enumerated element topology values defined 00125 * in the \c elemtypes datatype described in a \ref Root "previous section". 00126 * 00127 * Each subgroup contains a single DataSet named \c connectivity and an 00128 * optional subgroup named \c tags. The \c tags subgroup is described in the 00129 * \ref Dense "section on dense tag storage". 00130 * 00131 * The \c connectivity DataSet is an \f$ n \times m \f$ array of integer 00132 * values. The DataSet contains one row for each of the \c n contained 00133 * elements, where the connectivity of each element contains \c m IDs. For 00134 * all element types supported by MOAB, with the exception of polyhedra, 00135 * the element connectivity list is expected to contain only IDs 00136 * corresponding to nodes. 00137 * 00138 * Each element \c connectivity DataSet must have an integer attribute 00139 * named \c start_id . The elements defined in the connectivity table 00140 * are defined to have IDs beginning with this value and increasing 00141 * sequentially in the order that they are defined in the table. 00142 * 00143 * 00144 *\section Sets The sets Group 00145 * 00146 * The \c sets group contains the definitions of any entity sets stored 00147 * in the file. It contains 1 to 4 DataSets and the optional \c tags 00148 * subgroup. The \c contents, \c parents, and \c children data sets 00149 * are one dimensional arrays containing the concatenation of the 00150 * corresponding lists for all of the sets represented in the file. 00151 * 00152 * The \c lists DataSet is a \f$ n \times 4 \f$ table, having one 00153 * row of four integer values for each set. The first three values 00154 * for each set are the indices into the \c contents, \c children, 00155 * and \c parents DataSets, respectively, at which the \em last value 00156 * for set is stored. The contents, child, and parent lists for 00157 * sets are stored in the corresponding datasets in the same order as 00158 * the sets are listed in the \c lists DataSet, such that the index of 00159 * the first value in one of those tables is one greater than the 00160 * corresponding end index in the \em previous row of the table. The 00161 * number of content entries, parents, or children for a given set can 00162 * be calculated as the difference between the corresponding end index 00163 * entry for the current set and the same entry in the previous row 00164 * of the table. If the first set in the \c lists DataSet had no parent 00165 * sets, then the corresponding index in the third column of the table 00166 * would be \c -1. If it had one parent, the index would be \c 0. If it 00167 * had two parents, the index would be \c 1, as the first parent would be 00168 * stored at position 0 of the \c parents DataSet and the second at position 00169 * 1. 00170 * 00171 * The fourth column of the \c lists DataSet is a series of bit flags 00172 * defining some properties of the sets. The four bit values currently 00173 * defined are: 00174 * - 0x1 owner 00175 * - 0x2 unique 00176 * - 0x4 ordered 00177 * - 0x8 range compressed 00178 * 00179 * The fourth (most significant) bit indicates that, in the \c contents 00180 * data set, that the contents list for the corresponding set is stored 00181 * using a single range compression. Rather than storing the IDs of the 00182 * contained entities individually, each ID \c i is followed by a count 00183 * \c n indicating that the set contains the contiguous range of IDs 00184 * \f$ [i, i+n-1] \f$. 00185 * 00186 * The three least significant bits specify intended properties of the 00187 * set and are unrelated to how the set data is stored in the file. These 00188 * properties, described briefly from least significant bit to most 00189 * significant are: contained entities should track set membership; 00190 * the set should contain each entity only once (strict set); and 00191 * that the order of the entries in the set should be preserved. 00192 * 00193 * Similar to the \c nodes/coordinates and \c elements/.../connectivity 00194 * DataSets, the \c lists DataSet must have an integer attribute 00195 * named \c start_id . IDs are assigned to to sets in the order that 00196 * they occur in the \c lists table, beginning with the attribute value. 00197 * 00198 * The \c sets group may contain a subgroup names \c tags. The \c tags 00199 * subgroup is described in the \ref Dense "section on dense tag storage". 00200 * 00201 * 00202 * \section Tags The tags Group 00203 * 00204 * The \c tags group contains a sub-group for each tag defined 00205 * in the file. These sub-groups contain the definition of the 00206 * tag and may contain some or all of the tag values associated with 00207 * entities in the file. However, it should be noted that tag values 00208 * may also be stored in the "dense" format as described in the 00209 * \ref Dense "section on dense tag storage". 00210 * 00211 * Each sub-group of the \c tags group contains the definition for 00212 * a single tag. The name of each sub-group is the name of the 00213 * corresponding tag. Non-printable characters, characters 00214 * prohibited in group names in the HDF5 file format, and the 00215 * backslash ('\') character are encoded 00216 * in the name string by a backslash ('\') character followed by 00217 * the ASCII value of the character expressed as a pair of hexadecimal 00218 * digits. Thus the backslash character would be represented as \c \5C . 00219 * Each tag group should also contain a comment which contains the 00220 * unencoded tag name. 00221 * 00222 * The tag sub-group may have any or all of the following four attributes: 00223 * \c default, \c global, \c is_handle, and \c variable_length. 00224 * The \c default attribute, if present, 00225 * must contain a single tag value that is to be considered the 'default' 00226 * value of the tag. The \c global attribute, if present, must contain a 00227 * single tag value that is the value of the tag as set on the mesh instance 00228 * (MOAB terminology) or root set (ITAPS terminology.) The presence of the 00229 * \c is_handle attribute (the value, if any, is meaningless) indicates 00230 * that the tag values are to be considered entity IDs. After reading the 00231 * file, the reader should map any such tag values to whatever mechanism 00232 * it uses to reference the corresponding entities read from the file. 00233 * The presence of the \c variable_length attribute indicates that each 00234 * tag value is a variable-length array. The reader should rely on the 00235 * presence of this attribute rather than the presence of the \c var_indices 00236 * DataSet discussed below because the file may contain the definition of 00237 * a variable length tag without containing any values for that tag. In such 00238 * a case, the \c var_indices DataSet will not be present. 00239 * 00240 * Each tag sub-group will contain a committed type object named \c type . 00241 * This type must be the type instance used by the \c global and \c default 00242 * attributes discussed above and any tag value data sets. For fixed-length 00243 * tag data, the tag types understood by MOAB are: 00244 * - opaque data 00245 * - a single floating point value 00246 * - a single integer value 00247 * - a bit field 00248 * - an array of floating point values 00249 * - an array of integer values 00250 * Any other data types will be treated as opaque data. 00251 * For Variable-length tag data, MOAB expects the \c type object to be 00252 * one of: 00253 * - opaque data 00254 * - a single floating point value 00255 * - a single integer value 00256 * 00257 * For fixed-length tags, the tag sub-group may contain 'sparse' formatted 00258 * tag data, which is comprised of two data sets: \c id_list and \c values. 00259 * Both data sets must be 1-dimensional arrays of the same length. The 00260 * \c id_list data set contains a list of entity IDs and the \c values 00261 * data set contains a list of corresponding tag values. The data stored in 00262 * the \c values table must be of type \c type. Fixed-length tag values 00263 * may also be stored in the "dense" format as described in the 00264 * \ref Dense "section on dense tag storage". A mixture of both sparse- 00265 * and dense-formatted tag values may be present for a single tag. 00266 * 00267 * For variable-length tags the tag values, if any, are always stored 00268 * in the tag sub-group of the \c tags group and are represented by 00269 * three one-dimensional data sets: \c id_list, \c var_indices, and \c values. 00270 * Similar to the fixed-length sparse-formatted tag data, the \c id_list 00271 * contains the IDs of the entities for which tag values are defined. 00272 * The \c values dataset contains the concatenation of the tag values 00273 * for each of the entities referenced by ID in the \c id_list table, 00274 * in the order that the entities are referenced in the \c id_list table. 00275 * The \c var_indices table contains an index into the \c values data set 00276 * for each entity in \c id_list. The index indicates the position of 00277 * the \em last tag value for the entity in \c values. The index of 00278 * the first value is one greater than the 00279 * corresponding end index for the \em entry in \c var_indices. The 00280 * number of tag values for a given entity can 00281 * be calculated as the difference between the corresponding end index 00282 * entry for the current entity and the previous value in the \c var_indices 00283 * dataset. 00284 * 00285 * 00286 * \section Dense The tags Sub-Groups 00287 * 00288 * Data for fixed-length tags may also be stored in the \c tags sub-group 00289 * of the \c nodes, \c sets, and subgroups of the \c elements group. 00290 * Values for given tag are stored in a dataset within the \c tags sub-group 00291 * that has the following properties: 00292 * - The name must be the same as that of the tag definition in the main 00293 * \c tags group 00294 * - The type of the data set must be the committed type object stored 00295 * as \c /tstt/tags/<tagname>/type . 00296 * - The data set must have the same length as the data set in the 00297 * parent group with the \c start_id attribute. 00298 * 00299 * If dense-formatted data is specified for any entity in the group, then 00300 * it must be specified for every entity in the group. The table is 00301 * expected to contain one value for each entity in the corresponding 00302 * primary definition table (\c /tstt/nodes/coordinates , 00303 * \c /tstt/elements/<name>/connectivity , or \c /tstt/sets/list), in the 00304 * same order as the entities in that primary definition table. 00305 * 00306 */ 00307 00308 /** 00309 *\defgroup mhdf MHDF API for reading/writing MOAB-format HDF5 mesh files. 00310 */ 00311 /*@{*/ 00312 00313 00314 /** 00315 *\defgroup mhdf_status Error handling 00316 */ 00317 /*@{*/ 00318 00319 /** 00320 *\defgroup mhdf_group Element group handle 00321 */ 00322 /*@{*/ 00323 00324 00325 /** \brief Get an mhdf_ElemHandle object for the node data. 00326 * 00327 * \return A special element group handle used when specifying adjacency or 00328 * tag data for nodes. 00329 */ 00330 const char* 00331 mhdf_node_type_handle(void); 00332 00333 00334 /** \brief Return a special element group handle used to specify the set group. 00335 * 00336 * \return A special element group handle used to specify the set group 00337 * for reading/writing tag data on sets. 00338 */ 00339 const char* 00340 mhdf_set_type_handle(void); 00341 00342 #define MHDF_INDEX_TYPE H5T_NATIVE_LONG 00343 00344 /** \brief Given an element type Id, get the name. 00345 * Fails if buffer is not of sufficient size. 00346 * \param file_handle The file. 00347 * \param type_index The type index. Corresponds to indices into 00348 * the element type list passed to \ref mhdf_createFile. 00349 * \param buffer The buffer into which to copy the name. 00350 * \param buffer_size The length of <code>buffer</code>. 00351 * \param status Passed back status of API call. 00352 */ 00353 void 00354 mhdf_getElemName( mhdf_FileHandle file_handle, 00355 unsigned int type_index, 00356 char* buffer, size_t buffer_size, 00357 mhdf_Status* status ); 00358 00359 int 00360 mhdf_checkOpenHandles( mhdf_FileHandle handle, mhdf_Status* status ); 00361 00362 /** \brief Common close function for all data handle types. 00363 * 00364 * Close an hid_t-type handle returned from any of the following 00365 * functions. Any hid_t passed-back or returned must be closed via 00366 * this function to avoid resource loss. 00367 * 00368 * \param file The file the object pointed to by the passed data 00369 * handled exists int. 00370 * \param handle The data object to close. 00371 * \param status Passed back status of API call. 00372 */ 00373 void 00374 mhdf_closeData( mhdf_FileHandle file, 00375 hid_t handle, 00376 mhdf_Status* status ); 00377 00378 /**\brief Get start ID that will be assigned to next created dataset 00379 * 00380 * Get the first_id parameter that will be returned from the next 00381 * call to any of mhdf_createNodeCoords, mhdf_createConnectivity, 00382 * mhdf_createPolyConnectivity, or mhdf_createSetMeta 00383 */ 00384 void 00385 mhdf_getNextStartId( mhdf_FileHandle file, 00386 mhdf_index_t* start_id_out, 00387 mhdf_Status* status ); 00388 00389 /** \brief Write the file history as a list of strings. 00390 * 00391 * Each entry is composed of four strings: 00392 * application, version, date, and time. 00393 * 00394 * \param file The file. 00395 * \param strings An array of null-terminated strings. 00396 * \param num_strings The length of <code>strings</code> 00397 * \param status Passed back status of API call. 00398 */ 00399 void 00400 mhdf_writeHistory( mhdf_FileHandle file, 00401 const char** strings, 00402 int num_strings, 00403 mhdf_Status* status ); 00404 00405 /** \brief Read the file history as a list of strings. 00406 * 00407 * Each entry is composed of four strings: 00408 * application, version, date, and time. 00409 * 00410 * Strings and array are allocated with <code>malloc</code>. Caller must 00411 * release them by calling <code>free</code> 00412 * 00413 * \param file The file. 00414 * \param num_records_out The length of the returned array. 00415 * \param status Passed back status of API call. 00416 * \return An array of null-terminates strings. 00417 */ 00418 char** 00419 mhdf_readHistory( mhdf_FileHandle file, 00420 int* num_records_out, 00421 mhdf_Status* status ); 00422 /*@}*/ 00423 /** 00424 *\defgroup mhdf_node Node coordinate data. 00425 */ 00426 /*@{*/ 00427 00428 /* Node Coordinates */ 00429 00430 int 00431 mhdf_haveNodes( mhdf_FileHandle file_handle, mhdf_Status* status ); 00432 00433 00434 /** \brief Create new table for node coordinate data 00435 * 00436 * \param file_handle The file. 00437 * \param dimension Number of coordinate values per node. 00438 * \param num_nodes The number of nodes the table will contain. 00439 * \param first_node_id_out Nodes are assigned IDs sequentially in the 00440 * order they occur in the table, where the ID of the first 00441 * node in the table is this passed-back value. 00442 * \param status Passed back status of API call. 00443 * \return An HDF5 handle to the coordinate table. 00444 */ 00445 hid_t 00446 mhdf_createNodeCoords( mhdf_FileHandle file_handle, 00447 int dimension, 00448 long num_nodes, 00449 long* first_node_id_out, 00450 mhdf_Status* status ); 00451 00452 /** \brief Open table containing node coordinate data 00453 * 00454 * \param file_handle The file. 00455 * \param dimension_out Number of coordinate values per node. 00456 * \param num_nodes_out The number of nodes the table contains. 00457 * \param first_node_id_out Nodes are assigned IDs sequentially in the 00458 * order they occur in the table, where the ID of the first 00459 * node in the table is this passed-back value. 00460 * \param status Passed back status of API call. 00461 * \return An HDF5 handle to the coordinate table. 00462 */ 00463 hid_t 00464 mhdf_openNodeCoords( mhdf_FileHandle file_handle, 00465 long* num_nodes_out, 00466 int* dimension_out, 00467 long* first_node_id_out, 00468 mhdf_Status* status ); 00469 00470 hid_t 00471 mhdf_openNodeCoordsSimple( mhdf_FileHandle file_handle, mhdf_Status* status ); 00472 00473 /** \brief Write node coordinate data 00474 * 00475 * Write interleaved coordinate data for a block of nodes 00476 * 00477 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00478 * or <code>mhdf_openNodeCoords</code>. 00479 * \param offset Table row (node index) at which to start writing. 00480 * \param count Number of rows (number of nodes) to write. 00481 * \param coords Interleaved node coordinate data. 00482 * \param status Passed back status of API call. 00483 */ 00484 void 00485 mhdf_writeNodeCoords( hid_t data_handle, 00486 long offset, 00487 long count, 00488 const double* coords, 00489 mhdf_Status* status ); 00490 void 00491 mhdf_writeNodeCoordsWithOpt( hid_t data_handle, 00492 long offset, 00493 long count, 00494 const double* coords, 00495 hid_t write_prop, 00496 mhdf_Status* status ); 00497 00498 /** \brief Write node coordinate data 00499 * 00500 * Write a single coordinate value (e.g. the 'x' coordinate) for a 00501 * block of nodes. 00502 * 00503 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00504 * or <code>mhdf_openNodeCoords</code>. 00505 * \param offset Table row (node index) at which to start writing. 00506 * \param count Number of rows (number of nodes) to write. 00507 * \param dimension The coordinate to write (0->x, 1->y, ...) 00508 * \param coords Coordinate list. 00509 * \param status Passed back status of API call. 00510 */ 00511 void 00512 mhdf_writeNodeCoord( hid_t data_handle, 00513 long offset, 00514 long count, 00515 int dimension, 00516 const double* coords, 00517 mhdf_Status* status ); 00518 void 00519 mhdf_writeNodeCoordWithOpt( hid_t data_handle, 00520 long offset, 00521 long count, 00522 int dimension, 00523 const double* coords, 00524 hid_t write_prop, 00525 mhdf_Status* status ); 00526 00527 /** \brief Read node coordinate data 00528 * 00529 * Read interleaved coordinate data for a block of nodes 00530 * 00531 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00532 * or <code>mhdf_openNodeCoords</code>. 00533 * \param offset Table row (node index) at which to start reading. 00534 * \param count Number of rows (number of nodes) to read. 00535 * \param coordinates Buffer in which to write node coordinate data. 00536 * \param status Passed back status of API call. 00537 */ 00538 void 00539 mhdf_readNodeCoords( hid_t data_handle, 00540 long offset, 00541 long count, 00542 double* coordinates, 00543 mhdf_Status* status ); 00544 void 00545 mhdf_readNodeCoordsWithOpt( hid_t data_handle, 00546 long offset, 00547 long count, 00548 double* coordinates, 00549 hid_t read_prop, 00550 mhdf_Status* status ); 00551 00552 00553 /** \brief Read node coordinate data 00554 * 00555 * Read a single coordinate value (e.g. the 'x' coordinate) for a 00556 * block of nodes. 00557 * 00558 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00559 * or <code>mhdf_openNodeCoords</code>. 00560 * \param offset Table row (node index) at which to start reading. 00561 * \param count Number of rows (number of nodes) to read. 00562 * \param dimension The coordinate to read (0->x, 1->y, ...) 00563 * \param coords Buffer in which to write node coordinate data. 00564 * \param status Passed back status of API call. 00565 */ 00566 void 00567 mhdf_readNodeCoord( hid_t data_handle, 00568 long offset, 00569 long count, 00570 int dimension, 00571 double* coords, 00572 mhdf_Status* status ); 00573 void 00574 mhdf_readNodeCoordWithOpt( hid_t data_handle, 00575 long offset, 00576 long count, 00577 int dimension, 00578 double* coords, 00579 hid_t read_prop, 00580 mhdf_Status* status ); 00581 00582 /*@}*/ 00583 /** 00584 *\defgroup mhdf_conn Element connectivity data. 00585 */ 00586 /*@{*/ 00587 00588 /* Element Connectivity */ 00589 00590 /** \brief Add a new table of element data to the file. 00591 * 00592 * Add a element group to the file. 00593 * An element group is the data for a block of elements with the same 00594 * TSTT type and same number of nodes in their connectivity data. 00595 * (e.g. all the MBHEX20 elements). This function is also 00596 * used to create the groups for general polygon data and 00597 * general polyhedron data. The requirement that all elements 00598 * have the same number of nodes in their connectivity does not 00599 * apply for poly(gons|hedra). 00600 * 00601 * \param file_handle File in which to create the element type. 00602 * \param elem_handle The name to use for the element data. This 00603 * name is used as an identifier to reference the 00604 * data for this element type later. The selected 00605 * name also appears explicitly in the file and 00606 * therefore should be something 00607 * descriptive of the element type such as the 00608 * 'base type' and number of nodes (e.g. "Hex20"). 00609 * \param named_elem_type An index into the list of named element types 00610 * passed to \ref mhdf_createFile . 00611 * \param status Passed back status of API call. 00612 */ 00613 void 00614 mhdf_addElement( mhdf_FileHandle file_handle, 00615 const char* elem_handle, 00616 unsigned int named_elem_type, 00617 mhdf_Status* status ); 00618 00619 /** \brief Get the list of element groups in the file. 00620 * 00621 * Get the list of element groups in the file. 00622 * An element group is the data for a block of elements with the same 00623 * TSTT type and same number of nodes in their connectivity data. 00624 * (e.g. all the MBHEX20 elements). This function is also 00625 * used to retrieve the groups for general polygon data and 00626 * general polyhedron data. The requirement that all elements 00627 * have the same number of nodes in their connectivity does not 00628 * apply for poly(gons|hedra). 00629 * 00630 * \param file_handle The file. 00631 * \param count_out Memory location at which to store the 00632 * length of the returned array. 00633 * \param status Passed back status of API call. 00634 * \return An array of pointers to element group 00635 * names. This array is allocated as a 00636 * single memory block and should be freed 00637 * with <em>one</em> call to free(). 00638 */ 00639 char** 00640 mhdf_getElemHandles( mhdf_FileHandle file_handle, 00641 unsigned int* count_out, 00642 mhdf_Status* status ); 00643 00644 /** 00645 * \brief Get the element type name for a given element group handle. 00646 * 00647 * Fails if name is longer than <code>buf_len</code>. 00648 * 00649 * \param file_handle The file. 00650 * \param elem_handle One of the group names passed back from 00651 * \ref mhdf_getElemHandles 00652 * \param buffer A buffer to copy the name into. 00653 * \param buf_len The length of <code>buffer</code>. 00654 * \param status Passed back status of API call. 00655 */ 00656 void 00657 mhdf_getElemTypeName( mhdf_FileHandle file_handle, 00658 const char* elem_handle, 00659 char* buffer, size_t buf_len, 00660 mhdf_Status* status ); 00661 00662 /** \brief Check if an element group contains polygon or polyhedron 00663 * 00664 * Check if an element group contains general polygon or polyhedrons 00665 * rather than typically fixed-connectivity elements. 00666 * 00667 * \param file_handle The file. 00668 * \param elem_handle The element group. 00669 * \param status Passed back status of API call. 00670 * \return Zero if normal fixed-connectivity element data. Non-zero if 00671 * poly(gon/hedron) general-connectivity data. 00672 */ 00673 int 00674 mhdf_isPolyElement( mhdf_FileHandle file_handle, 00675 const char* elem_handle, 00676 mhdf_Status* status ); 00677 00678 /** \brief Create connectivity table for an element group 00679 * 00680 * Create fixed-connectivity data for an element group. 00681 * Do NOT use this function for poly(gon/hedron) data. 00682 * 00683 * \param file_handle The file. 00684 * \param elem_handle The element group. 00685 * \param num_nodes_per_elem The number of nodes in the connectivity data 00686 * for each element. 00687 * \param num_elements The number of elements to be written to the table. 00688 * \param first_elem_id_out Elements are assigned global IDs in 00689 * sequential blocks where the block is the table in 00690 * which their connectivity data is written and the 00691 * sequence is the sequence in which they are written 00692 * in that table. The global ID for the first element 00693 * in this group is passed back at this address. The 00694 * global IDs for all other elements in the table are 00695 * assigned in the sequence in which they are written 00696 * in the table. 00697 * \param status Passed back status of API call. 00698 * \return The HDF5 handle to the connectivity data. 00699 */ 00700 hid_t 00701 mhdf_createConnectivity( mhdf_FileHandle file_handle, 00702 const char* elem_handle, 00703 int num_nodes_per_elem, 00704 long num_elements, 00705 long* first_elem_id_out, 00706 mhdf_Status* status ); 00707 00708 00709 /** \brief Open connectivity table for an element group 00710 * 00711 * Open fixed-connectivity data for an element group. 00712 * Do NOT use this function for poly(gon/hedron) data. Use 00713 * <code>mhdf_isPolyElement</code> or <code>mhdf_getTsttElemType</code> 00714 * to check if the data is poly(gon|hedron) data before calling this 00715 * function to open the data. 00716 * 00717 * \param file_handle The file. 00718 * \param elem_handle The element group. 00719 * \param num_nodes_per_elem_out Used to pass back the number of nodes 00720 * in each element. 00721 * \param num_elements_out Pass back the number of elements in the table. 00722 * \param first_elem_id_out Elements are assigned global IDs in 00723 * sequential blocks where the block is the table in 00724 * which their connectivity data is written and the 00725 * sequence is the sequence in which they are written 00726 * in that table. The global ID for the first element 00727 * in this group is passed back at this address. The 00728 * global IDs for all other elements in the table are 00729 * assigned in the sequence in which they are written 00730 * in the table. 00731 * \param status Passed back status of API call. 00732 * \return The HDF5 handle to the connectivity data. 00733 */ 00734 hid_t 00735 mhdf_openConnectivity( mhdf_FileHandle file_handle, 00736 const char* elem_handle, 00737 int* num_nodes_per_elem_out, 00738 long* num_elements_out, 00739 long* first_elem_id_out, 00740 mhdf_Status* status ); 00741 00742 hid_t 00743 mhdf_openConnectivitySimple( mhdf_FileHandle file_handle, 00744 const char* elem_handle, 00745 mhdf_Status* status ); 00746 00747 00748 /** \brief Write element coordinate data 00749 * 00750 * Write interleaved fixed-connectivity element data for a block of elements. 00751 * Note: Do not use this for polygon or polyhedron data. 00752 * 00753 * \param data_handle Handle returned from <code>mhdf_createConnectivity</code> 00754 * or <code>mhdf_openConnectivity</code>. 00755 * \param offset Table row (element index) at which to start writing. 00756 * \param count Number of rows (number of elements) to write. 00757 * \param hdf_integer_type The type of the integer data in node_id_list. 00758 * Typically <code>H5T_NATIVE_INT</code> or 00759 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00760 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00761 * \param node_id_list Interleaved connectivity data specified as global node IDs. 00762 * \param status Passed back status of API call. 00763 */ 00764 void 00765 mhdf_writeConnectivity( hid_t data_handle, 00766 long offset, 00767 long count, 00768 hid_t hdf_integer_type, 00769 const void* node_id_list, 00770 mhdf_Status* status ); 00771 void 00772 mhdf_writeConnectivityWithOpt( hid_t data_handle, 00773 long offset, 00774 long count, 00775 hid_t hdf_integer_type, 00776 const void* node_id_list, 00777 hid_t write_prop, 00778 mhdf_Status* status ); 00779 00780 /** \brief Read element coordinate data 00781 * 00782 * Read interleaved fixed-connectivity element data for a block of elements. 00783 * Note: Do not use this for polygon or polyhedron data. 00784 * 00785 * \param data_handle Handle returned from <code>mhdf_createConnectivity</code> 00786 * or <code>mhdf_openConnectivity</code>. 00787 * \param offset Table row (element index) at which to start read. 00788 * \param count Number of rows (number of elements) to read. 00789 * \param hdf_integer_type The type of the integer data in node_id_list. 00790 * Typically <code>H5T_NATIVE_INT</code> or 00791 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00792 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00793 * \param node_id_list Pointer to memory at which to write interleaved 00794 * connectivity data specified as global node IDs. 00795 * \param status Passed back status of API call. 00796 */ 00797 void 00798 mhdf_readConnectivity( hid_t data_handle, 00799 long offset, 00800 long count, 00801 hid_t hdf_integer_type, 00802 void* node_id_list, 00803 mhdf_Status* status ); 00804 void 00805 mhdf_readConnectivityWithOpt( hid_t data_handle, 00806 long offset, 00807 long count, 00808 hid_t hdf_integer_type, 00809 void* node_id_list, 00810 hid_t read_prop, 00811 mhdf_Status* status ); 00812 00813 /* Poly(gon|hedra) */ 00814 00815 00816 /** \brief Create a new table for polygon or polyhedron connectivity data. 00817 * 00818 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00819 * One list is the concatenation of the the connectivity data for 00820 * all the polys in the group. The other contains one value per 00821 * poly where that value is the index of the last entry in the 00822 * connectivity of the corresponding poly. The ID 00823 * list for polygons contains global node IDs. The ID list for polyhedra 00824 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00825 * elements.) 00826 * 00827 * \param file_handle The file to write. 00828 * \param elem_handle The element group. 00829 * \param num_poly The total number number of polygons or polyhedra to 00830 * be written in the table. 00831 * \param data_list_length The total number of values to be written to the 00832 * table (the number of polys plus the sum of the number 00833 * of entities in each poly's connectivity data.) 00834 * \param first_id_out Elements are assigned global IDs in 00835 * sequential blocks where the block is the table in 00836 * which their connectivity data is written and the 00837 * sequence is the sequence in which they are written 00838 * in that table. The global ID for the first element 00839 * in this group is passed back at this address. The 00840 * global IDs for all other elements in the table are 00841 * assigned in the sequence in which they are written 00842 * in the table. 00843 * \param idx_and_id_handles_out The handles for the index list and 00844 * connectivity list, respectively. 00845 * \param status Passed back status of API call. 00846 */ 00847 void 00848 mhdf_createPolyConnectivity( mhdf_FileHandle file_handle, 00849 const char* elem_handle, 00850 long num_poly, 00851 long data_list_length, 00852 long* first_id_out, 00853 hid_t idx_and_id_handles_out[2], 00854 mhdf_Status* status ); 00855 00856 /** \brief Open a table of polygon or polyhedron connectivity data. 00857 * 00858 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00859 * One list is the concatenation of the the connectivity data for 00860 * all the polys in the group. The other contains one value per 00861 * poly where that value is the index of the last entry in the 00862 * connectivity of the corresponding poly. The ID 00863 * list for polygons contains global node IDs. The ID list for polyhedra 00864 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00865 * elements.) 00866 * 00867 * \param file_handle The file to write. 00868 * \param elem_handle The element group. 00869 * \param num_poly_out The total number number of polygons or polyhedra to 00870 * be written in the table. 00871 * \param data_list_length_out The total number of values to be written to the 00872 * table (the number of polys plus the sum of the number 00873 * of entities in each poly's connectivity data.) 00874 * \param first_id_out Elements are assigned global IDs in 00875 * sequential blocks where the block is the table in 00876 * which their connectivity data is written and the 00877 * sequence is the sequence in which they are written 00878 * in that table. The global ID for the first element 00879 * in this group is passed back at this address. The 00880 * global IDs for all other elements in the table are 00881 * assigned in the sequence in which they are written 00882 * in the table. 00883 * \param idx_and_id_handles_out The handles for the index list and 00884 * connectivity list, respectively. 00885 * \param status Passed back status of API call. 00886 */ 00887 void 00888 mhdf_openPolyConnectivity( mhdf_FileHandle file_handle, 00889 const char* elem_handle, 00890 long* num_poly_out, 00891 long* data_list_length_out, 00892 long* first_id_out, 00893 hid_t idx_and_id_handles_out[2], 00894 mhdf_Status* status ); 00895 00896 /** \brief Write polygon or polyhedron index data. 00897 * 00898 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00899 * One list is the concatenation of the the connectivity data for 00900 * all the polys in the group. The other contains one value per 00901 * poly where that value is the index of the last entry in the 00902 * connectivity of the corresponding poly. The ID 00903 * list for polygons contains global node IDs. The ID list for polyhedra 00904 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00905 * elements.) 00906 * 00907 * This function writes the index list. 00908 * 00909 * \param poly_handle The handle returned from 00910 * <code>mhdf_createPolyConnectivity</code> or 00911 * <code>mhdf_openPolyConnectivity</code>. 00912 * \param offset The offset in the table at which to write. The 00913 * offset is in terms of the integer values in the table, 00914 * not the count of polys. 00915 * \param count The size of the integer list to write. 00916 * \param hdf_integer_type The type of the integer data in <code>id_list</code>. 00917 * Typically <code>H5T_NATIVE_INT</code> or 00918 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00919 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00920 * \param index_list The index list for the polys. 00921 * \param status Passed back status of API call. 00922 */ 00923 void 00924 mhdf_writePolyConnIndices( hid_t poly_handle, 00925 long offset, 00926 long count, 00927 hid_t hdf_integer_type, 00928 const void* index_list, 00929 mhdf_Status* status ); 00930 void 00931 mhdf_writePolyConnIndicesWithOpt( hid_t poly_handle, 00932 long offset, 00933 long count, 00934 hid_t hdf_integer_type, 00935 const void* index_list, 00936 hid_t write_prop, 00937 mhdf_Status* status ); 00938 00939 /** \brief Write polygon or polyhedron connectivity data. 00940 * 00941 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00942 * One list is the concatenation of the the connectivity data for 00943 * all the polys in the group. The other contains one value per 00944 * poly where that value is the index of the last entry in the 00945 * connectivity of the corresponding poly. The ID 00946 * list for polygons contains global node IDs. The ID list for polyhedra 00947 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00948 * elements.) 00949 * 00950 * This function writes the connectivity/ID list. 00951 * 00952 * \param poly_handle The handle returned from 00953 * <code>mhdf_createPolyConnectivity</code> or 00954 * <code>mhdf_openPolyConnectivity</code>. 00955 * \param offset The offset in the table at which to write. The 00956 * offset is in terms of the integer values in the table, 00957 * not the count of polys. 00958 * \param count The size of the integer list to write. 00959 * \param hdf_integer_type The type of the integer data in <code>id_list</code>. 00960 * Typically <code>H5T_NATIVE_INT</code> or 00961 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00962 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00963 * \param id_list The count/global ID list specifying the connectivity 00964 * of the polys. 00965 * \param status Passed back status of API call. 00966 */ 00967 void 00968 mhdf_writePolyConnIDs( hid_t poly_handle, 00969 long offset, 00970 long count, 00971 hid_t hdf_integer_type, 00972 const void* id_list, 00973 mhdf_Status* status ); 00974 void 00975 mhdf_writePolyConnIDsWithOpt( hid_t poly_handle, 00976 long offset, 00977 long count, 00978 hid_t hdf_integer_type, 00979 const void* id_list, 00980 hid_t write_prop, 00981 mhdf_Status* status ); 00982 00983 /** \brief Read polygon or polyhedron index data. 00984 * 00985 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00986 * One list is the concatenation of the the connectivity data for 00987 * all the polys in the group. The other contains one value per 00988 * poly where that value is the index of the last entry in the 00989 * connectivity of the corresponding poly. The ID 00990 * list for polygons contains global node IDs. The ID list for polyhedra 00991 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00992 * elements.) 00993 * 00994 * \param poly_handle The handle returned from 00995 * <code>mhdf_createPolyConnectivity</code> or 00996 * <code>mhdf_openPolyConnectivity</code>. 00997 * \param offset The offset in the table at which to read. The 00998 * offset is in terms of the integer values in the table, 00999 * not the count of polys. 01000 * \param count The size of the integer list to read. 01001 * \param hdf_integer_type The type of the integer data as written into memory. 01002 * Typically <code>H5T_NATIVE_INT</code> or 01003 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01004 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01005 * \param index_list The memory location at which to write the indices. 01006 * \param status Passed back status of API call. 01007 */ 01008 void 01009 mhdf_readPolyConnIndices( hid_t poly_handle, 01010 long offset, 01011 long count, 01012 hid_t hdf_integer_type, 01013 void* index_list, 01014 mhdf_Status* status ); 01015 void 01016 mhdf_readPolyConnIndicesWithOpt( hid_t poly_handle, 01017 long offset, 01018 long count, 01019 hid_t hdf_integer_type, 01020 void* index_list, 01021 hid_t read_prop, 01022 mhdf_Status* status ); 01023 01024 /** \brief Read polygon or polyhedron connectivity data. 01025 * 01026 * Poly (polygon or polyhedron) connectivity is stored as two lists. 01027 * One list is the concatenation of the the connectivity data for 01028 * all the polys in the group. The other contains one value per 01029 * poly where that value is the index of the last entry in the 01030 * connectivity of the corresponding poly. The ID 01031 * list for polygons contains global node IDs. The ID list for polyhedra 01032 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 01033 * elements.) 01034 * 01035 * \param poly_handle The handle returned from 01036 * <code>mhdf_createPolyConnectivity</code> or 01037 * <code>mhdf_openPolyConnectivity</code>. 01038 * \param offset The offset in the table at which to read. The 01039 * offset is in terms of the integer values in the table, 01040 * not the count of polys. 01041 * \param count The size of the integer list to read. 01042 * \param hdf_integer_type The type of the integer data as written into memory. 01043 * Typically <code>H5T_NATIVE_INT</code> or 01044 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01045 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01046 * \param id_list The memory location at which to write the connectivity data. 01047 * \param status Passed back status of API call. 01048 */ 01049 void 01050 mhdf_readPolyConnIDs( hid_t poly_handle, 01051 long offset, 01052 long count, 01053 hid_t hdf_integer_type, 01054 void* id_list, 01055 mhdf_Status* status ); 01056 void 01057 mhdf_readPolyConnIDsWithOpt( hid_t poly_handle, 01058 long offset, 01059 long count, 01060 hid_t hdf_integer_type, 01061 void* id_list, 01062 hid_t read_prop, 01063 mhdf_Status* status ); 01064 /*@}*/ 01065 /** 01066 *\defgroup mhdf_adj Adjacency data. 01067 * 01068 * Adjacency data is formated as a sequence of integer groups where 01069 * the first entry in each group is the ID of the element for which 01070 * adjacencies are being specified, the second value is the count of 01071 * adjacent entities, and the remainder of the group is the list of 01072 * IDs of the adjacent entities. 01073 */ 01074 /*@{*/ 01075 01076 01077 /** \brief Create adjacency data table for nodes, elements, polys, etc. 01078 * 01079 * Create file object for adjacency data for a nodes or a specified 01080 * element group. 01081 * 01082 * Adjacency data is formated as a sequence of integer groups where 01083 * the first entry in each group is the ID of the element for which 01084 * adjacencies are being specified, the second value is the count of 01085 * adjacent entities, and the remainder of the group is the list of 01086 * IDs of the adjacent entities. 01087 * 01088 * \param file_handle The file. 01089 * \param elem_handle The element group (or the result of 01090 * <code>mhdf_node_type_handle</code> for nodes) for 01091 * which the adjacency data is to be specified. 01092 * \param adj_list_size The total number of integer values contained 01093 * in the adjacency data for the specified element group. 01094 * \param status Passed back status of API call. 01095 * \return The HDF5 handle to the connectivity data. 01096 */ 01097 hid_t 01098 mhdf_createAdjacency( mhdf_FileHandle file_handle, 01099 const char* elem_handle, 01100 long adj_list_size, 01101 mhdf_Status* status ); 01102 01103 /** \brief Check if adjacency data is present in the file for the specified 01104 * element group. 01105 * 01106 * \param file The file. 01107 * \param elem_handle A handle to an element group. 01108 * \param status Passed back status of API call. 01109 */ 01110 int 01111 mhdf_haveAdjacency( mhdf_FileHandle file, 01112 const char* elem_handle, 01113 mhdf_Status* status ); 01114 01115 /** \brief Open adjacency data table for nodes, elements, polys, etc. 01116 * 01117 * Open the file object containing adjacency data for a nodes or a specified 01118 * element group. 01119 * 01120 * Adjacency data is formated as a sequence of integer groups where 01121 * the first entry in each group is the ID of the element for which 01122 * adjacencies are being specified, the second value is the count of 01123 * adjacent entities, and the remainder of the group is the list of 01124 * IDs of the adjacent entities. 01125 * 01126 * \param file_handle The file. 01127 * \param elem_handle The element group (or the result of 01128 * <code>mhdf_node_type_handle</code> for nodes) for 01129 * which the adjacency data is to be specified. 01130 * \param adj_list_size The total number of integer values contained 01131 * in the adjacency data for the specified element group. 01132 * \param status Passed back status of API call. 01133 * \return The HDF5 handle to the connectivity data. 01134 */ 01135 hid_t 01136 mhdf_openAdjacency( mhdf_FileHandle file_handle, 01137 const char* elem_handle, 01138 long* adj_list_size, 01139 mhdf_Status* status ); 01140 01141 /** \brief Write node/element adjacency data 01142 * 01143 * Write adjacency data. 01144 * 01145 * Adjacency data is formated as a sequence of integer groups where 01146 * the first entry in each group is the ID of the element for which 01147 * adjacencies are being specified, the second value is the count of 01148 * adjacent entities, and the remainder of the group is the list of 01149 * IDs of the adjacent entities. 01150 * 01151 * \param data_handle Handle returned from <code>mhdf_createAdjacency</code> 01152 * or <code>mhdf_openAdjacency</code>. 01153 * \param offset List position at which to start writing. Offset is 01154 * from the count if integer values written, NOT a count 01155 * of the number of elements for which adjacency data 01156 * is written. 01157 * \param count Number of integer values to write. 01158 * \param hdf_integer_type The type of the integer data in <code>adj_list_data</code>. 01159 * Typically <code>H5T_NATIVE_INT</code> or 01160 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01161 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01162 * \param adj_list_data Adjacency data to write. 01163 * \param status Passed back status of API call. 01164 */ 01165 void 01166 mhdf_writeAdjacency( hid_t data_handle, 01167 long offset, 01168 long count, 01169 hid_t hdf_integer_type, 01170 const void* adj_list_data, 01171 mhdf_Status* status ); 01172 void 01173 mhdf_writeAdjacencyWithOpt( hid_t data_handle, 01174 long offset, 01175 long count, 01176 hid_t hdf_integer_type, 01177 const void* adj_list_data, 01178 hid_t write_prop, 01179 mhdf_Status* status ); 01180 01181 /** \brief Read node/element adjacency data 01182 * 01183 * Read adjacency data. 01184 * 01185 * Adjacency data is formated as a sequence of integer groups where 01186 * the first entry in each group is the ID of the element for which 01187 * adjacencies are being specified, the second value is the count of 01188 * adjacent entities, and the remainder of the group is the list of 01189 * IDs of the adjacent entities. 01190 * 01191 * \param data_handle Handle returned from <code>mhdf_createAdjacency</code> 01192 * or <code>mhdf_openAdjacency</code>. 01193 * \param offset List position at which to start reading. Offset is 01194 * from the count if integer values written, NOT a count 01195 * of the number of elements for which adjacency data 01196 * is written. 01197 * \param count Number of integer values to reading. 01198 * \param hdf_integer_type The type of the integer data in <code>adj_list_data_out</code>. 01199 * Typically <code>H5T_NATIVE_INT</code> or 01200 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01201 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01202 * \param adj_list_data_out Pointer to memory at which to write adjacency data. 01203 * \param status Passed back status of API call. 01204 */ 01205 void 01206 mhdf_readAdjacency( hid_t data_handle, 01207 long offset, 01208 long count, 01209 hid_t hdf_integer_type, 01210 void* adj_list_data_out, 01211 mhdf_Status* status ); 01212 void 01213 mhdf_readAdjacencyWithOpt( hid_t data_handle, 01214 long offset, 01215 long count, 01216 hid_t hdf_integer_type, 01217 void* adj_list_data_out, 01218 hid_t read_prop, 01219 mhdf_Status* status ); 01220 01221 /*@}*/ 01222 01223 /** 01224 *\defgroup mhdf_set Meshset data. 01225 * 01226 * Meshset data is divided into three groups of data. The set-list/meta-information table, 01227 * the set contents table and the set children table. Each is written and read independently. 01228 * 01229 * The set list table contains one row for each set. Each row contains four values: 01230 * {content list end index, child list end index, parent list end index, and flags}. The flags 01231 * value is a collection of bits with 01232 * values defined in \ref mhdf_set_flag . The all the flags except \ref mhdf_SET_RANGE_BIT are 01233 * saved properties of the mesh data and are not relevant to the actual file in any way. The 01234 * \ref mhdf_SET_RANGE_BIT flag is a toggle for how the meshset contents (not children) are saved. 01235 * It is an internal property of the file format and should not be passed on to the mesh database. 01236 * The content list end index and child list end index are the indices of the last entry for the 01237 * set in the contents and children tables respectively. In the case where a set has either no 01238 * children or no contents, the last index of should be the same as the last index of the previous 01239 * set in the table, or -1 for the first set in the table. Thus the first index is always one 01240 * greater than the last index of the previous set. If the first index, calculated as one greater 01241 * that the last index of the previous set is greater than the last index of the current set, then 01242 * there are no values in the corresponding contents or children table for that set. 01243 * 01244 * The set contents table is a vector of integer global IDs that is the concatenation of the contents 01245 * data for all of the mesh sets. The values are stored corresponding to the order of the sets 01246 * in the set list table. Depending on the value of \ref mhdf_SET_RANGE_BIT in the flags field of 01247 * the set list table, the contents for a specific set may be stored in one of two formats. If the 01248 * flag is set, the contents list is a list of pairs where each pair is a starting global Id and a 01249 * count. For each pair, the set contains the range of global Ids beginning at the start value. 01250 * If the \ref mhdf_SET_RANGE_BIT flag is not set, the meshset contents are a simple list of global Ids. 01251 * 01252 * The meshset child table is a vector of integer global IDs. It is a concatenation of the child 01253 * lists for all the mesh sets, in the order the sets occur in the meshset list table. The values 01254 * are always simple lists. The child table may never contain ranges of IDs. 01255 */ 01256 /*@{*/ 01257 01258 01259 /** 01260 *\defgroup mhdf_set_flag Set flag bits 01261 */ 01262 /*@{*/ 01263 01264 /** \brief Make entities in set aware of owning set (MOAB-specific?)*/ 01265 #define mhdf_SET_OWNER_BIT 0x1 01266 /** \brief Set cannot contain duplicates */ 01267 #define mhdf_SET_UNIQUE_BIT 0x2 01268 /** \brief Set order is preserved */ 01269 #define mhdf_SET_ORDER_BIT 0x4 01270 01271 /** \brief The bit specifying set storage format. 01272 * 01273 * If this bit is set, then the contents of a set (not the children) 01274 * is written as set of ranges, where each range is of the form 01275 * {global start id, count}. For such a range, the set contains the 01276 * <code>count</code> entities with sequential global IDs beginning 01277 * with the specified start ID. If this bit is not set in the set flags, 01278 * the contents of the set are stored as a simple list of global IDs. 01279 */ 01280 #define mhdf_SET_RANGE_BIT 0x8 01281 01282 /*@}*/ 01283 01284 /** \brief Create table holding list of meshsets and their properties. 01285 * 01286 * The set table contains description of sets, but not contents or 01287 * children. The table is a <code>n x 4</code> matrix of values. 01288 * One row for each of <code>n</code> sets. Each row contains the end index 01289 * for the set in the contents table, the end index for the set in the children 01290 * table, the end index for the set in the parents table, and the set flags, 01291 * respectively. The \ref mhdf_SET_RANGE_BIT 01292 * bit in the flags specifies the format of the contents list for each set. 01293 * See a description of the \ref mhdf_SET_RANGE_BIT flag for a description 01294 * of the two possible data formats. The index values in the first two columns 01295 * of the table are the index of the <em>last</em> value for the set in the corresponding 01296 * contents and children lists. The first index is always one greater than the last index 01297 * for the previous set in the table. The first index of the first set in the table is 01298 * implicitly zero. A special value of -1 in the appropriate column should be used to 01299 * indicate that the first set contains no contents or has no children. For any other set, 01300 * if the last index for the set is the same as that of the previous set, it has no data 01301 * in the corresponding list. 01302 * 01303 *\param file_handle The file. 01304 *\param num_sets The number of sets in the table. 01305 *\param first_set_id_out The global ID that will be assigned to the first 01306 * set in the table. All subsequent sets in the table 01307 * will be assigned sequential global IDs. 01308 * \param status Passed back status of API call. 01309 *\return The handle to the set meta-data table. 01310 */ 01311 hid_t 01312 mhdf_createSetMeta( mhdf_FileHandle file_handle, 01313 long num_sets, 01314 long* first_set_id_out, 01315 mhdf_Status* status ); 01316 01317 /** \brief Check if file contains any sets 01318 * 01319 *\param file The file. 01320 *\param have_set_data_out If non-null set to 1 if file contains table 01321 * of set contents, zero otherwise. 01322 *\param have_set_child_out If non-null set to 1 if file contains table 01323 * of set children, zero otherwise. 01324 *\param have_set_parents_out If non-null set to 1 if file contains table 01325 * of set parents, zero otherwise. 01326 * \param status Passed back status of API call. 01327 *\return Zero if the file does not contain any sets, one if it does. 01328 */ 01329 int 01330 mhdf_haveSets( mhdf_FileHandle file, 01331 int* have_set_data_out, 01332 int* have_set_child_out, 01333 int* have_set_parents_out, 01334 mhdf_Status* status ); 01335 01336 /** \brief Open table holding list of meshsets and their properties. 01337 * 01338 * Open set list. 01339 * See \ref mhdf_createSetMeta or \ref mhdf_set for a description of this data. 01340 * 01341 *\param file_handle The file. 01342 *\param num_sets_out The number of sets in the table. 01343 *\param first_set_id_out The global ID that will of the first 01344 * set in the table. All subsequent sets in the table 01345 * have sequential global IDs. 01346 * \param status Passed back status of API call. 01347 *\return The handle to the set meta-data table. 01348 */ 01349 hid_t 01350 mhdf_openSetMeta( mhdf_FileHandle file_handle, 01351 long* num_sets_out, 01352 long* first_set_id_out, 01353 mhdf_Status* status ); 01354 01355 hid_t 01356 mhdf_openSetMetaSimple( mhdf_FileHandle file_handle, mhdf_Status* status ); 01357 01358 /** \brief Read list of sets and meta-information about sets. 01359 * 01360 * Read set descriptions. See \ref mhdf_createSetMeta or \ref mhdf_set 01361 * for a description of this data. 01362 * 01363 *\param data_handle The handle returned from \ref mhdf_createSetMeta or 01364 * \ref mhdf_openSetMeta. 01365 *\param offset The offset (set index) to begin reading at. 01366 *\param count The number of rows (sets, integer triples) to read. 01367 *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>. 01368 * Typically <code>H5T_NATIVE_INT</code> or 01369 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01370 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01371 * \param status Passed back status of API call. 01372 *\param set_desc_data The memory location at which to write the data. 01373 */ 01374 void 01375 mhdf_readSetMeta( hid_t data_handle, 01376 long offset, 01377 long count, 01378 hid_t hdf_integer_type, 01379 void* set_desc_data, 01380 mhdf_Status* status ); 01381 void 01382 mhdf_readSetMetaWithOpt( hid_t data_handle, 01383 long offset, 01384 long count, 01385 hid_t hdf_integer_type, 01386 void* set_desc_data, 01387 hid_t read_prop, 01388 mhdf_Status* status ); 01389 01390 /** \brief Read only the flags portion of the set description table 01391 * 01392 * Read flags for each set from the set description table. 01393 * See \ref mhdf_createSetMeta for a description of this data. 01394 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01395 *\param offset The offset (set index) at which to begin reading. 01396 *\param count The number of values (number of sets) to read. 01397 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01398 *\param set_flag_data Array of integers. 01399 *\param status Location at which to store status of API call. 01400 */ 01401 void 01402 mhdf_readSetFlags( hid_t data_handle, 01403 long offset, 01404 long count, 01405 hid_t hdf_integer_type, 01406 void* set_flag_data, 01407 mhdf_Status* status ); 01408 void 01409 mhdf_readSetFlagsWithOpt( hid_t data_handle, 01410 long offset, 01411 long count, 01412 hid_t hdf_integer_type, 01413 void* set_flag_data, 01414 hid_t read_prop, 01415 mhdf_Status* status ); 01416 01417 01418 /** \brief Read only the content end indices portion of the set description table 01419 * 01420 * For each set, read the last index of that set's data in the set 01421 * contents table. 01422 * 01423 * NOTE: This is a signed value. Any sets w/out contents that occur 01424 * first in the list will have an end index of -1. 01425 * 01426 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01427 *\param offset The offset (set index) at which to begin reading. 01428 *\param count The number of values (number of sets) to read. 01429 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01430 *\param end_indices_out Array of indices. 01431 *\param status Location at which to store status of API call. 01432 */ 01433 void 01434 mhdf_readSetContentEndIndices( hid_t data_handle, 01435 long offset, 01436 long count, 01437 hid_t hdf_integer_type, 01438 void* end_indices_out, 01439 mhdf_Status* status ); 01440 void 01441 mhdf_readSetContentEndIndicesWithOpt( hid_t data_handle, 01442 long offset, 01443 long count, 01444 hid_t hdf_integer_type, 01445 void* end_indices_out, 01446 hid_t read_prop, 01447 mhdf_Status* status ); 01448 01449 /** \brief Read only the child end indices portion of the set description table 01450 * 01451 * For each set, read the last index of that set's data in the set 01452 * children table. 01453 * 01454 * NOTE: This is a signed value. Any sets w/out contents that occur 01455 * first in the list will have an end index of -1. 01456 * 01457 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01458 *\param offset The offset (set index) at which to begin reading. 01459 *\param count The number of values (number of sets) to read. 01460 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01461 *\param end_indices_out Array of indices. 01462 *\param status Location at which to store status of API call. 01463 */ 01464 void 01465 mhdf_readSetChildEndIndices( hid_t data_handle, 01466 long offset, 01467 long count, 01468 hid_t hdf_integer_type, 01469 void* end_indices_out, 01470 mhdf_Status* status ); 01471 void 01472 mhdf_readSetChildEndIndicesWithOpt( hid_t data_handle, 01473 long offset, 01474 long count, 01475 hid_t hdf_integer_type, 01476 void* end_indices_out, 01477 hid_t read_prop, 01478 mhdf_Status* status ); 01479 01480 /** \brief Read only the parent end indices portion of the set description table 01481 * 01482 * For each set, read the last index of that set's data in the set 01483 * parents table. 01484 * 01485 * NOTE: This is a signed value. Any sets w/out contents that occur 01486 * first in the list will have an end index of -1. 01487 * 01488 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01489 *\param offset The offset (set index) at which to begin reading. 01490 *\param count The number of values (number of sets) to read. 01491 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01492 *\param end_indices_out Array of indices. 01493 *\param status Location at which to store status of API call. 01494 */ 01495 void 01496 mhdf_readSetParentEndIndices( hid_t data_handle, 01497 long offset, 01498 long count, 01499 hid_t hdf_integer_type, 01500 void* end_indices_out, 01501 mhdf_Status* status ); 01502 void 01503 mhdf_readSetParentEndIndicesWithOpt( hid_t data_handle, 01504 long offset, 01505 long count, 01506 hid_t hdf_integer_type, 01507 void* end_indices_out, 01508 hid_t read_prop, 01509 mhdf_Status* status ); 01510 01511 01512 /** \brief Write list of sets and meta-information about sets. 01513 * 01514 * Write set descriptions. See \ref mhdf_createSetMeta or \ref mhdf_set for a 01515 * description of the data format. 01516 * 01517 *\param data_handle The handle returned from \ref mhdf_createSetMeta or 01518 * \ref mhdf_openSetMeta. 01519 *\param offset The offset (set index) to begin writing at. 01520 *\param count The number of rows (sets, integer triples) to write. 01521 *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>. 01522 * Typically <code>H5T_NATIVE_INT</code> or 01523 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01524 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01525 *\param set_desc_data The data to write. 01526 * \param status Passed back status of API call. 01527 */ 01528 void 01529 mhdf_writeSetMeta( hid_t data_handle, 01530 long offset, 01531 long count, 01532 hid_t hdf_integer_type, 01533 const void* set_desc_data, 01534 mhdf_Status* status ); 01535 void 01536 mhdf_writeSetMetaWithOpt( hid_t data_handle, 01537 long offset, 01538 long count, 01539 hid_t hdf_integer_type, 01540 const void* set_desc_data, 01541 hid_t write_prop, 01542 mhdf_Status* status ); 01543 01544 /** \brief Create file object to hold list of meshset contents. 01545 * 01546 * Create set contents data object. 01547 * The format of this data is a vector of integer values which is the 01548 * concatenation of the contents list for all the meshsets. The length 01549 * and format of the data for each set is stored in the set meta table. 01550 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01551 * description of that data. 01552 * 01553 *\param file_handle The file. 01554 *\param data_list_size The total length (number of integer values) to 01555 * be written for all the sets. 01556 *\param status Passed back status of API call. 01557 *\return A handle to the table. 01558 */ 01559 hid_t 01560 mhdf_createSetData( mhdf_FileHandle file_handle, 01561 long data_list_size, 01562 mhdf_Status* status ); 01563 01564 /** \brief Open the file object for the meshset contents. 01565 * 01566 * Open set contents data object. 01567 * The format of this data is a vector of integer values which is the 01568 * concatenation of the contents list for all the meshsets. The length 01569 * and format of the data for each set is stored in the set meta table. 01570 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01571 * description of that data. 01572 * 01573 *\param file_handle The file. 01574 *\param data_list_size_out The length of the table. 01575 *\param status Passed back status of API call. 01576 *\return A handle to the table. 01577 */ 01578 hid_t 01579 mhdf_openSetData( mhdf_FileHandle file_handle, 01580 long* data_list_size_out, 01581 mhdf_Status* status ); 01582 01583 /** \brief Write set contents. 01584 * 01585 * Write data specifying entities contained in sets. 01586 * The format of this data is a vector of integer values which is the 01587 * concatenation of the contents list for all the meshsets. The length 01588 * and format of the data for each set is stored in the set meta table. 01589 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01590 * description of that data. 01591 * 01592 *\param set_handle The handle returned from \ref mhdf_createSetData 01593 * or \ref mhdf_openSetData . 01594 *\param offset The position at which to write into the integer vector. 01595 *\param count The number of values to write into the data vector. 01596 *\param hdf_integer_type The type of the integer data in <code>set_data</code>. 01597 * Typically <code>H5T_NATIVE_INT</code> or 01598 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01599 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01600 *\param set_data The data to write. 01601 *\param status Passed back status of API call. 01602 */ 01603 void 01604 mhdf_writeSetData( hid_t set_handle, 01605 long offset, 01606 long count, 01607 hid_t hdf_integer_type, 01608 const void* set_data, 01609 mhdf_Status* status ); 01610 void 01611 mhdf_writeSetDataWithOpt( hid_t set_handle, 01612 long offset, 01613 long count, 01614 hid_t hdf_integer_type, 01615 const void* set_data, 01616 hid_t write_prop, 01617 mhdf_Status* status ); 01618 01619 /** \brief Read set contents. 01620 * 01621 * Read data specifying entities contained in sets. 01622 * The format of this data is a vector of integer values which is the 01623 * concatenation of the contents list for all the meshsets. The length 01624 * and format of the data for each set is stored in the set meta table. 01625 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01626 * description of that data. 01627 * 01628 *\param set_handle The handle returned from \ref mhdf_createSetData 01629 * or \ref mhdf_openSetData . 01630 *\param offset The position at which to read from the integer vector. 01631 *\param count The number of values to read from the data vector. 01632 *\param hdf_integer_type The type of the integer data in <code>set_data</code>. 01633 * Typically <code>H5T_NATIVE_INT</code> or 01634 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01635 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01636 *\param set_data A pointer to memory at which to store the read data. 01637 *\param status Passed back status of API call. 01638 */ 01639 void 01640 mhdf_readSetData( hid_t set_handle, 01641 long offset, 01642 long count, 01643 hid_t hdf_integer_type, 01644 void* set_data, 01645 mhdf_Status* status ); 01646 void 01647 mhdf_readSetDataWithOpt( hid_t set_handle, 01648 long offset, 01649 long count, 01650 hid_t hdf_integer_type, 01651 void* set_data, 01652 hid_t read_prop, 01653 mhdf_Status* status ); 01654 01655 /** \brief Create file object for storing the set child list 01656 * 01657 * Create a data group for the list of set children. 01658 * The format of this data is the concatenation of the lists of 01659 * global IDs of child sets for each set. The order of the sets and 01660 * the number of children for each set is contained in the set meta table. 01661 * (See \ref mhdf_createSetMeta ). 01662 * 01663 *\param file_handle The file 01664 *\param child_list_size The total length of the data (the sum of the 01665 * number of children for each set.) 01666 *\param status Passed back status of API call. 01667 *\return A handle to the data object in the file. 01668 */ 01669 hid_t 01670 mhdf_createSetChildren( mhdf_FileHandle file_handle, 01671 long child_list_size, 01672 mhdf_Status* status ); 01673 01674 /** \brief Open the file object containing the set child list 01675 * 01676 * Open the data group containing the list of set children. 01677 * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 01678 * a description of this data. 01679 * 01680 *\param file_handle The file 01681 *\param child_list_size The total length of the data (the sum of the 01682 * number of children for each set.) 01683 *\param status Passed back status of API call. 01684 *\return A handle to the data object in the file. 01685 */ 01686 hid_t 01687 mhdf_openSetChildren( mhdf_FileHandle file_handle, 01688 long* child_list_size, 01689 mhdf_Status* status ); 01690 01691 /** \brief Create file object for storing the set parent list 01692 * 01693 * Create a data group for the list of set parents. 01694 * The format of this data is the concatenation of the lists of 01695 * global IDs of parent sets for each set. The order of the sets and 01696 * the number of parents for each set is contained in the set meta table. 01697 * (See \ref mhdf_createSetMeta ). 01698 * 01699 *\param file_handle The file 01700 *\param parent_list_size The total length of the data (the sum of the 01701 * number of parents for each set.) 01702 *\param status Passed back status of API call. 01703 *\return A handle to the data object in the file. 01704 */ 01705 hid_t 01706 mhdf_createSetParents( mhdf_FileHandle file_handle, 01707 long parent_list_size, 01708 mhdf_Status* status ); 01709 01710 /** \brief Open the file object containing the set parent list 01711 * 01712 * Open the data group containing the list of set parents. 01713 * See \ref mhdf_createSetParents and \ref mhdf_createSetMeta for 01714 * a description of this data. 01715 * 01716 *\param file_handle The file 01717 *\param parent_list_size The total length of the data (the sum of the 01718 * number of parents for each set.) 01719 *\param status Passed back status of API call. 01720 *\return A handle to the data object in the file. 01721 */ 01722 hid_t 01723 mhdf_openSetParents( mhdf_FileHandle file_handle, 01724 long* parent_list_size, 01725 mhdf_Status* status ); 01726 01727 /** \brief Write set parent/child list 01728 * 01729 * Write the list of parent or child IDs for sets. 01730 * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 01731 * a description of this data. 01732 * 01733 *\param data_handle The value returned from \ref mhdf_createSetChildren 01734 * or \ref mhdf_openSetChildren. 01735 *\param offset The offset into the list of global IDs. 01736 *\param count The number of global IDs to write. 01737 *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>. 01738 * Typically <code>H5T_NATIVE_INT</code> or 01739 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01740 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01741 *\param id_list The data to write. 01742 *\param status Passed back status of API call. 01743 */ 01744 void 01745 mhdf_writeSetParentsChildren( hid_t data_handle, 01746 long offset, 01747 long count, 01748 hid_t hdf_integer_type, 01749 const void* id_list, 01750 mhdf_Status* status ); 01751 void 01752 mhdf_writeSetParentsChildrenWithOpt( hid_t data_handle, 01753 long offset, 01754 long count, 01755 hid_t hdf_integer_type, 01756 const void* id_list, 01757 hid_t write_prop, 01758 mhdf_Status* status ); 01759 01760 /** \brief Read set parent/child list 01761 * 01762 * Read from the list of parent or child IDs for sets. 01763 * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 01764 * a description of this data. 01765 * 01766 *\param data_handle The value returned from \ref mhdf_createSetChildren 01767 * or \ref mhdf_openSetChildren. 01768 *\param offset The offset into the list of global IDs. 01769 *\param count The number of global IDs to read. 01770 *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>. 01771 * Typically <code>H5T_NATIVE_INT</code> or 01772 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01773 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01774 *\param id_list Pointer to memory in which to the read data. 01775 *\param status Passed back status of API call. 01776 */ 01777 void 01778 mhdf_readSetParentsChildren( hid_t data_handle, 01779 long offset, 01780 long count, 01781 hid_t hdf_integer_type, 01782 void* id_list, 01783 mhdf_Status* status ); 01784 void 01785 mhdf_readSetParentsChildrenWithOpt( hid_t data_handle, 01786 long offset, 01787 long count, 01788 hid_t hdf_integer_type, 01789 void* id_list, 01790 hid_t read_prop, 01791 mhdf_Status* status ); 01792 01793 /*@}*/ 01794 01795 /** 01796 *\defgroup mhdf_tag Tag data. 01797 * 01798 * The data for each tag can be stored in two places/formats: sparse and/or 01799 * dense. The data may be stored in both, but there should not be redundant 01800 * values for the same entity. 01801 * 01802 * Dense tag data is stored as multiple tables of tag values, one for each 01803 * element group. (Note: special \ref mhdf_ElemHandle values are available 01804 * for accessing dense tag data on nodes or meshsets via the \ref mhdf_node_type_handle 01805 * and \ref mhdf_set_type_handle functions.) Each dense tag table should contain 01806 * the same number of entries as the element connectivity table. The tag values 01807 * are associated with the corresponding element in the connectivity table. 01808 * 01809 * Sparse tag data is stored as a global table pair for each tag type. The first 01810 * if the pair of tables is a list of Global IDs. The second is the corresponding 01811 * tag value for each entity in the ID list. 01812 */ 01813 /*@{*/ 01814 01815 01816 /** 01817 *\defgroup mhdf_tag_flag Tag type values (MOAB-specific) 01818 */ 01819 /*@{*/ 01820 01821 /** \brief Was dense tag data in mesh database */ 01822 #define mhdf_DENSE_TYPE 2 01823 /** \brief Was sparse tag data in mesh database */ 01824 #define mhdf_SPARSE_TYPE 1 01825 /** \brief Was bit-field tag data in mesh database */ 01826 #define mhdf_BIT_TYPE 0 01827 /** \brief Unused */ 01828 #define mhdf_MESH_TYPE 3 01829 01830 /*@}*/ 01831 01832 /** \brief Make type native-endian. 01833 * 01834 * Given an atomic HDF5 data type, return the built-in type 01835 * that matches the class of the passed type and is the specified 01836 * size. 01837 * 01838 * This function is provided to allow converting the stored tag 01839 * type in a file to the preferred type for it's representation 01840 * in memory when reading tag values. 01841 * 01842 * This function works only for atomic types. The returned type 01843 * will be a pre-defined HDF5 object and does not need to be 01844 * closed/released. 01845 * 01846 *\param input_type The type to convert. 01847 *\param size The desired size in bytes. 01848 *\param status Passed back status of API call. 01849 *\return The converted type. 01850 */ 01851 hid_t 01852 mhdf_getNativeType( hid_t input_type, 01853 int size, 01854 mhdf_Status* status ); 01855 01856 /** \brief Add a tag to the file 01857 * 01858 * Add a new tag to the file. This function must be called 01859 * to define the tag characteristics before values for the 01860 * tag can be written. 01861 * 01862 *\param file_handle The file 01863 *\param tag_name The tag name 01864 *\param tag_type The tag type. 01865 *\param size If tag_type == mhdf_BITFIELD, the number of 01866 * bits. If tag_type == mhdf_OPAQUE, the size 01867 * of the opaque type in bytes. Otherwise the 01868 * length of the array of tag_type entities associated 01869 * with each mesh entity, or 1 for a scalar value. 01870 *\param storage MOAB storage type (dense, sparse, etc.) 01871 *\param default_value Default value for tag, or NULL if none. 01872 *\param global_value Global value for tag, or NULL if none. 01873 *\param hdf_type If non-zero, assumed to be a user-specified type 01874 * for opaque data. Ignored if tag_type is not 01875 * mhdf_OPAQUE. 01876 *\param hdf_base_type Ignored if hdf_type is non-zero. If hdf_type is 01877 * zero and this type is non-zero, it is used either 01878 * as the type or as the base type for an array type for 01879 * default_value and global_value, respectively. Typically 01880 * used to specify the input data type for mhdf_ENTITY_ID 01881 * tags. 01882 */ 01883 void 01884 mhdf_createTag( mhdf_FileHandle file_handle, 01885 const char* tag_name, 01886 enum mhdf_TagDataType tag_type, 01887 int size, 01888 int storage, 01889 const void* default_value, 01890 const void* global_value, 01891 hid_t hdf_type, 01892 hid_t mhdf_base_type, 01893 mhdf_Status* status ); 01894 01895 /**\brief Get handle to HDF5 type object for tag data */ 01896 hid_t 01897 mhdf_getTagDataType( mhdf_FileHandle file_handle, 01898 const char* tag_name, 01899 mhdf_Status* status ); 01900 01901 01902 /** \brief Add variable-length tag to file 01903 * 01904 * Add a new tag to the file. This function must be called 01905 * to define the tag characteristics before values for the 01906 * tag can be written. Use this function if the tag values 01907 * are not fixed-length. 01908 * 01909 *\param file_handle The file 01910 *\param tag_name The tag name 01911 *\param tag_type The tag type. 01912 *\param storage MOAB storage type (dense, sparse, etc.) 01913 *\param default_value Default value for tag, or NULL if none. 01914 *\param default_value_length Length of default value. 01915 *\param global_value Global value for tag, or NULL if none. 01916 *\param global_value_length Length of global value. 01917 *\param hdf_type If non-zero, assumed to be a user-specified type 01918 * for opaque data. Ignored if tag_type is not 01919 * mhdf_OPAQUE. 01920 *\param hdf_base_type Ignored if hdf_type is non-zero. If hdf_type is 01921 * zero and this type is non-zero, it is used either 01922 * as the type or as the base type for an array type for 01923 * default_value and global_value, respectively. Typically 01924 * used to specify the input data type for mhdf_ENTITY_ID 01925 * tags. 01926 */ 01927 void 01928 mhdf_createVarLenTag( mhdf_FileHandle file_handle, 01929 const char* tag_name, 01930 enum mhdf_TagDataType tag_type, 01931 int storage, 01932 const void* default_value, 01933 int default_value_length, 01934 const void* global_value, 01935 int global_value_length, 01936 hid_t hdf_type, 01937 hid_t hdf_base_type, 01938 mhdf_Status* status ); 01939 01940 01941 /** \brief Get the number of tags in the file. 01942 * 01943 *\param file_handle The file. 01944 *\param status Passed back status of API call. 01945 *\return The number of tags. 01946 */ 01947 int 01948 mhdf_getNumberTags( mhdf_FileHandle file_handle, 01949 mhdf_Status* status ); 01950 01951 /** \brief Get the name for each tag defined in the file. 01952 * 01953 *\param file_handle The file. 01954 *\param num_names_out The length of the returned array of strings. 01955 *\param status Passed back status of API call. 01956 *\return An array of null-terminated strings. The array 01957 * and each string is allocated with <code>malloc</code>. 01958 * The caller should release this memory by calling 01959 * <code>free</code> for each string and the array. 01960 */ 01961 char** 01962 mhdf_getTagNames( mhdf_FileHandle file_handle, 01963 int* num_names_out, 01964 mhdf_Status* status ); 01965 01966 /** \brief Get the description of a specified tag. 01967 * 01968 * Get everything about a tag except the actual values. 01969 * 01970 *\param file_handle The file. 01971 *\param tag_name The name of the tag to retrieve the data for. 01972 *\param class_out The TSTT class of the tag data. 01973 *\param size_out Depends on value of class_out: 01974 * - mhdf_OPAQUE - size of opaque data in bytes 01975 * - mhdf_BITFIELD - number of bits 01976 * - if data is fixed-length array, length of array 01977 * - if data is single value, 1 01978 * - if data is a variable-length array, -1 01979 *\param tstt_storage_out The value of the TSTT enum for storage (dense, sparse, etc.) 01980 *\param have_default_out Non-zero if file contains a default value for the tag. 01981 * Length of default value if variable-lenth tag. 01982 *\param have_global_out Non-zero if the file contains a global/mesh value for the tag. 01983 *\param have_sparse_out Non-zero if the file contains a sparse data table for this tag. 01984 */ 01985 void 01986 mhdf_getTagInfo( mhdf_FileHandle file_handle, 01987 const char* tag_name, 01988 enum mhdf_TagDataType* class_out, 01989 int* size_out, 01990 int* tstt_storage_out, 01991 int* have_default_out, 01992 int* have_global_out, 01993 int* have_sparse_out, 01994 mhdf_Status* status ); 01995 01996 01997 01998 /** \brief Get the default and global values of the tag. 01999 * 02000 *\param file_handle The file. 02001 *\param tag_name The tag name. 02002 *\param output_data_type The HDF5 type for the memory into which the 02003 * tag data is to be written. If zero, then 02004 * the value(s) will be read as opaque data. 02005 *\param default_value Memory location at which to write the default 02006 * value of the tag. 02007 *\param global_value If the tag has a global value, the memory location 02008 * at which to write that value. 02009 *\param status Passed back status of API call. 02010 */ 02011 void 02012 mhdf_getTagValues( mhdf_FileHandle file_handle, 02013 const char* tag_name, 02014 hid_t output_data_type, 02015 void* default_value, 02016 void* global_value, 02017 mhdf_Status* status ); 02018 02019 /** \brief Check if the file contains dense tag data for the specified tag and element group. 02020 * 02021 * Check if there is dense tag data for a given element type for the specified 02022 * tag. 02023 * 02024 *\param file_handle The file. 02025 *\param tag_name The tag. 02026 *\param elem_group The element group handle, or the return value of 02027 * \ref mhdf_node_type_handle or \ref mhdf_set_type_handle 02028 * for nodes or sets respectively. 02029 *\param status Passed back status of API call. 02030 *\return Non-zero if file contains specified data. Zero otherwise. 02031 */ 02032 int 02033 mhdf_haveDenseTag( mhdf_FileHandle file_handle, 02034 const char* tag_name, 02035 const char* elem_group, 02036 mhdf_Status* status ); 02037 02038 /** \brief Create an object to hold dense tag values for a given element group. 02039 * 02040 *\param file_handle The file. 02041 *\param tag_name The tag. 02042 *\param elem_group The element group handle, or the return value of 02043 * \ref mhdf_node_type_handle or \ref mhdf_set_type_handle 02044 * for nodes or sets respectively. 02045 *\param num_values The number of tag values to be written. Must be 02046 * The same as the number of elements in the group. 02047 * Specified here to allow tag values to be written 02048 * before node coordinates, element connectivity or meshsets. 02049 *\param status Passed back status of API call. 02050 *\return Handle to data object in file. 02051 */ 02052 hid_t 02053 mhdf_createDenseTagData( mhdf_FileHandle file_handle, 02054 const char* tag_name, 02055 const char* elem_group, 02056 long num_values, 02057 mhdf_Status* status ); 02058 02059 /** \brief Open the object containing dense tag values for a given element group. 02060 * 02061 *\param file_handle The file. 02062 *\param tag_name The tag. 02063 *\param elem_group The element group handle, or the return value of 02064 * \ref mhdf_node_type_handle or \ref mhdf_set_type_handle 02065 * for nodes or sets respectively. 02066 *\param num_values_out The number of tag values to be written. Must be 02067 * The same as the number of elements in the group. 02068 *\param status Passed back status of API call. 02069 *\return Handle to data object in file. 02070 */ 02071 hid_t 02072 mhdf_openDenseTagData( mhdf_FileHandle file_handle, 02073 const char* tag_name, 02074 const char* elem_group, 02075 long* num_values_out, 02076 mhdf_Status* status ); 02077 02078 /** \brief Create file objects to store sparse tag data 02079 * 02080 * Create the file objects to store all sparse data for a given tag in. The 02081 * sparse data is stored in a pair of objects. The first is a vector of 02082 * global IDs. The second is a vector of tag values for each entity specified 02083 * in the list of global IDs. 02084 * 02085 *\param file_handle The file. 02086 *\param tag_name The tag. 02087 *\param num_values The number of tag values to be written. 02088 *\param entities_and_values_out The handles to the file objects. 02089 * The first is the vector of global IDs. The second 02090 * is the list of corresponding tag values. 02091 *\param status Passed back status of API call. 02092 */ 02093 void 02094 mhdf_createSparseTagData( mhdf_FileHandle file_handle, 02095 const char* tag_name, 02096 long num_values, 02097 hid_t entities_and_values_out[2], 02098 mhdf_Status* status ); 02099 02100 /** \brief Create file objects to store (sparse) variable-length tag data 02101 * 02102 * Create the file objects to store all sparse data for a given tag in. The 02103 * sparse data is stored in a pair of objects. The first is a vector of 02104 * global IDs. The second is a vector of tag values for each entity specified 02105 * in the list of global IDs. 02106 * 02107 *\param file_handle The file. 02108 *\param tag_name The tag. 02109 *\param num_entities The number of entities for which tag values are to be stored 02110 *\param num_values The total number of scalar values to be written (the 02111 * total number of bytes of data for all tags for opaque 02112 * data.) 02113 *\param entities_and_values_out The handles to the file objects. 02114 * The first is the vector of global IDs. The second 02115 * is the list of corresponding tag values. The third 02116 * is the handle to the index table. 02117 *\param status Passed back status of API call. 02118 */ 02119 void 02120 mhdf_createVarLenTagData( mhdf_FileHandle file_handle, 02121 const char* tag_name, 02122 long num_entities, 02123 long num_values, 02124 hid_t entities_and_values_out[3], 02125 mhdf_Status* status ); 02126 02127 /** \brief Create file objects to read sparse tag data 02128 * 02129 * Open the file objects containing all sparse data for a given tag in. The 02130 * sparse data is stored in a pair of objects. The first is a vector of 02131 * global IDs. The second is a vector of tag values for each entity specified 02132 * in the list of global IDs. For variable-length tags, a third table 02133 * containing end offsets for each tag value is returned in the third 02134 * position of the output hid_t array (see mhdf_readSparseTagIndices.) 02135 * 02136 *\param file_handle The file. 02137 *\param tag_name The tag. 02138 *\param num_entity_out The number of entities for which there are tag values. 02139 *\param num_values_out The number of data values. For fixed-length tags, 02140 * this is the same as num_entity_out. For 02141 * variable-length tags, it is the total number of 02142 * values in the data table. 02143 *\param entities_and_values_out The handles to the pair of file objects. 02144 * The first is the vector of global IDs. The second 02145 * is the list of corresponding tag values. The third 02146 * is the handle to the index table, iff the tag is 02147 * variable-length. If the tag is fixed-length, this 02148 * value is not set. 02149 *\param status Passed back status of API call. 02150 */ 02151 void 02152 mhdf_openSparseTagData( mhdf_FileHandle file_handle, 02153 const char* tag_name, 02154 long* num_entity_out, 02155 long* num_values_out, 02156 hid_t entities_and_values_out[3], 02157 mhdf_Status* status ); 02158 02159 /** \brief Write Global ID list for sparse tag data 02160 * 02161 *\param id_handle The first handle passed back from either 02162 * \ref mhdf_createSparseTagData or 02163 * \ref mhdf_openSparseTagData. 02164 *\param offset The offset at which to begin writing. 02165 *\param count The number of global IDs to write. 02166 *\param hdf_integer_type The type of the integer data in <code>id_list</code>. 02167 * Typically <code>H5T_NATIVE_INT</code> or 02168 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 02169 * The HDF class of this type object <em>must</em> be H5T_INTEGER 02170 *\param id_list The list of global IDs to write. 02171 *\param status Passed back status of API call. 02172 */ 02173 void 02174 mhdf_writeSparseTagEntities( hid_t id_handle, 02175 long offset, 02176 long count, 02177 hid_t hdf_integer_type, 02178 const void* id_list, 02179 mhdf_Status* status ); 02180 void 02181 mhdf_writeSparseTagEntitiesWithOpt( hid_t id_handle, 02182 long offset, 02183 long count, 02184 hid_t hdf_integer_type, 02185 const void* id_list, 02186 hid_t write_prop, 02187 mhdf_Status* status ); 02188 02189 02190 02191 /** \brief Write tag values 02192 * 02193 *\param value_handle The second handle passed back from either 02194 * \ref mhdf_createSparseTagData or 02195 * \ref mhdf_openSparseTagData; or the handle 02196 * returned by \ref mhdf_createDenseTagData or 02197 * \ref mhdf_openDenseTagData. 02198 *\param offset The offset at which to begin writing. 02199 *\param count The number of tag values to write. 02200 *\param hdf_tag_data_type The type of the data in memory. 02201 * It must be possible for the HDF library to convert 02202 * between this type and the type the tag data is stored 02203 * as. 02204 *\param tag_data The list of tag values to write. 02205 *\param status Passed back status of API call. 02206 */ 02207 void 02208 mhdf_writeTagValues( hid_t value_handle, 02209 long offset, 02210 long count, 02211 hid_t hdf_tag_data_type, 02212 const void* tag_data, 02213 mhdf_Status* status ); 02214 void 02215 mhdf_writeTagValuesWithOpt( hid_t value_handle, 02216 long offset, 02217 long count, 02218 hid_t hdf_tag_data_type, 02219 const void* tag_data, 02220 hid_t write_prop, 02221 mhdf_Status* status ); 02222 02223 /**\brief Write sparse tag end indices for variable-length tag data 02224 * 02225 * Write sparse tag end indices for variable-length tag data. 02226 * Each value in the list is the *last* index (zero-based) into the tag 02227 * data for the corresponding entity. 02228 * 02229 *\param tag_handle handle to the data object to write to. 02230 *\param offset The offset into the table at which to begin writting 02231 *\param count The number of values to write. 02232 *\param hdf_integer_type The type of the values pointed to by end_indices 02233 * (must be an integer type). 02234 *\param end_indices The values to store in the table. 02235 *\param status Output: API result. 02236 */ 02237 void 02238 mhdf_writeSparseTagIndices( hid_t tag_handle, 02239 long offset, 02240 long count, 02241 hid_t hdf_integer_type, 02242 const void* end_indices, 02243 mhdf_Status* status ); 02244 void 02245 mhdf_writeSparseTagIndicesWithOpt( hid_t tag_handle, 02246 long offset, 02247 long count, 02248 hid_t hdf_integer_type, 02249 const void* end_indices, 02250 hid_t write_prop, 02251 mhdf_Status* status ); 02252 02253 /** \brief Read Global ID list for sparse tag data 02254 * 02255 *\param id_handle The first handle passed back from either 02256 * \ref mhdf_createSparseTagData or 02257 * \ref mhdf_openSparseTagData. 02258 *\param offset The offset at which to begin reading. 02259 *\param count The number of global IDs to read. 02260 *\param hdf_integer_type The type of the integer data in <code>id_list</code>. 02261 * Typically <code>H5T_NATIVE_INT</code> or 02262 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 02263 * The HDF class of this type object <em>must</em> be H5T_INTEGER 02264 *\param id_list The memory location at which to store the global IDs. 02265 *\param status Passed back status of API call. 02266 */ 02267 void 02268 mhdf_readSparseTagEntities( hid_t id_handle, 02269 long offset, 02270 long count, 02271 hid_t hdf_integer_type, 02272 void* id_list, 02273 mhdf_Status* status ); 02274 void 02275 mhdf_readSparseTagEntitiesWithOpt( hid_t id_handle, 02276 long offset, 02277 long count, 02278 hid_t hdf_integer_type, 02279 void* id_list, 02280 hid_t read_prop, 02281 mhdf_Status* status ); 02282 02283 /** \brief Read tag values 02284 * 02285 *\param value_handle The second handle passed back from either 02286 * \ref mhdf_createSparseTagData or 02287 * \ref mhdf_openSparseTagData; or the handle 02288 * returned by \ref mhdf_createDenseTagData or 02289 * \ref mhdf_openDenseTagData. 02290 *\param offset The offset at which to begin reading. 02291 *\param count The number of tag values to read. 02292 *\param hdf_type The type of the data in memory. If this is specified, 02293 * it must be possible for the HDF library to convert 02294 * between this type and the type the tag data is stored 02295 * as. If zero, the values will be read as opaque data. 02296 *\param memory Memory location at which to store tag values. 02297 *\param status Passed back status of API call. 02298 */ 02299 void 02300 mhdf_readTagValues( hid_t value_handle, 02301 long offset, 02302 long count, 02303 hid_t hdf_type, 02304 void* memory, 02305 mhdf_Status* status ); 02306 void 02307 mhdf_readTagValuesWithOpt( hid_t value_handle, 02308 long offset, 02309 long count, 02310 hid_t hdf_type, 02311 void* memory, 02312 hid_t read_prop, 02313 mhdf_Status* status ); 02314 02315 02316 /**\brief Read sparse tag end indices for variable-length tag data 02317 * 02318 * Read sparse tag end indices for variable-length tag data. 02319 * Each value in the list is the *last* index (zero-based) into the tag 02320 * data for the corresponding entity. 02321 * 02322 *\param tag_handle handle to the data object to read from. 02323 *\param offset The offset into the table at which to begin reading 02324 *\param count The number of values to read. 02325 *\param hdf_integer_type The type of the values pointed to by end_indices 02326 * (must be an integer type). 02327 *\param end_indices Memory in which to store the data read from the table. 02328 *\param status Output: API result. 02329 */ 02330 void 02331 mhdf_readSparseTagIndices( hid_t tag_handle, 02332 long offset, 02333 long count, 02334 hid_t hdf_integer_type, 02335 void* end_indices, 02336 mhdf_Status* status ); 02337 void 02338 mhdf_readSparseTagIndicesWithOpt( hid_t tag_handle, 02339 long offset, 02340 long count, 02341 hid_t hdf_integer_type, 02342 void* end_indices, 02343 hid_t read_prop, 02344 mhdf_Status* status ); 02345 02346 /*@}*/ 02347 02348 02349 /*@}*/ 02350 02351 02352 #ifdef __cplusplus 02353 } /* extern "C" */ 02354 #endif 02355 02356 #endif