MOAB: Mesh Oriented datABase
(version 5.4.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 *\defgroup mhdf_status Error handling 00315 */ 00316 /*@{*/ 00317 00318 /** 00319 *\defgroup mhdf_group Element group handle 00320 */ 00321 /*@{*/ 00322 00323 /** \brief Get an mhdf_ElemHandle object for the node data. 00324 * 00325 * \return A special element group handle used when specifying adjacency or 00326 * tag data for nodes. 00327 */ 00328 const char* mhdf_node_type_handle( void ); 00329 00330 /** \brief Return a special element group handle used to specify the set group. 00331 * 00332 * \return A special element group handle used to specify the set group 00333 * for reading/writing tag data on sets. 00334 */ 00335 const char* mhdf_set_type_handle( void ); 00336 00337 #define MHDF_INDEX_TYPE H5T_NATIVE_LONG 00338 00339 /** \brief Given an element type Id, get the name. 00340 * Fails if buffer is not of sufficient size. 00341 * \param file_handle The file. 00342 * \param type_index The type index. Corresponds to indices into 00343 * the element type list passed to \ref mhdf_createFile. 00344 * \param buffer The buffer into which to copy the name. 00345 * \param buffer_size The length of <code>buffer</code>. 00346 * \param status Passed back status of API call. 00347 */ 00348 void mhdf_getElemName( mhdf_FileHandle file_handle, 00349 unsigned int type_index, 00350 char* buffer, 00351 size_t buffer_size, 00352 mhdf_Status* status ); 00353 00354 int mhdf_checkOpenHandles( mhdf_FileHandle handle, mhdf_Status* status ); 00355 00356 /** \brief Common close function for all data handle types. 00357 * 00358 * Close an hid_t-type handle returned from any of the following 00359 * functions. Any hid_t passed-back or returned must be closed via 00360 * this function to avoid resource loss. 00361 * 00362 * \param file The file the object pointed to by the passed data 00363 * handled exists int. 00364 * \param handle The data object to close. 00365 * \param status Passed back status of API call. 00366 */ 00367 void mhdf_closeData( mhdf_FileHandle file, hid_t handle, mhdf_Status* status ); 00368 00369 /**\brief Get start ID that will be assigned to next created dataset 00370 * 00371 * Get the first_id parameter that will be returned from the next 00372 * call to any of mhdf_createNodeCoords, mhdf_createConnectivity, 00373 * mhdf_createPolyConnectivity, or mhdf_createSetMeta 00374 */ 00375 void mhdf_getNextStartId( mhdf_FileHandle file, mhdf_index_t* start_id_out, mhdf_Status* status ); 00376 00377 /** \brief Write the file history as a list of strings. 00378 * 00379 * Each entry is composed of four strings: 00380 * application, version, date, and time. 00381 * 00382 * \param file The file. 00383 * \param strings An array of null-terminated strings. 00384 * \param num_strings The length of <code>strings</code> 00385 * \param status Passed back status of API call. 00386 */ 00387 void mhdf_writeHistory( mhdf_FileHandle file, const char** strings, int num_strings, mhdf_Status* status ); 00388 00389 /** \brief Read 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 * Strings and array are allocated with <code>malloc</code>. Caller must 00395 * release them by calling <code>free</code> 00396 * 00397 * \param file The file. 00398 * \param num_records_out The length of the returned array. 00399 * \param status Passed back status of API call. 00400 * \return An array of null-terminates strings. 00401 */ 00402 char** mhdf_readHistory( mhdf_FileHandle file, int* num_records_out, mhdf_Status* status ); 00403 /*@}*/ 00404 /** 00405 *\defgroup mhdf_node Node coordinate data. 00406 */ 00407 /*@{*/ 00408 00409 /* Node Coordinates */ 00410 00411 int mhdf_haveNodes( mhdf_FileHandle file_handle, mhdf_Status* status ); 00412 00413 /** \brief Create new table for node coordinate data 00414 * 00415 * \param file_handle The file. 00416 * \param dimension Number of coordinate values per node. 00417 * \param num_nodes The number of nodes the table will contain. 00418 * \param first_node_id_out Nodes are assigned IDs sequentially in the 00419 * order they occur in the table, where the ID of the first 00420 * node in the table is this passed-back value. 00421 * \param status Passed back status of API call. 00422 * \return An HDF5 handle to the coordinate table. 00423 */ 00424 hid_t mhdf_createNodeCoords( mhdf_FileHandle file_handle, 00425 int dimension, 00426 long num_nodes, 00427 long* first_node_id_out, 00428 mhdf_Status* status ); 00429 00430 /** \brief Open table containing node coordinate data 00431 * 00432 * \param file_handle The file. 00433 * \param dimension_out Number of coordinate values per node. 00434 * \param num_nodes_out The number of nodes the table contains. 00435 * \param first_node_id_out Nodes are assigned IDs sequentially in the 00436 * order they occur in the table, where the ID of the first 00437 * node in the table is this passed-back value. 00438 * \param status Passed back status of API call. 00439 * \return An HDF5 handle to the coordinate table. 00440 */ 00441 hid_t mhdf_openNodeCoords( mhdf_FileHandle file_handle, 00442 long* num_nodes_out, 00443 int* dimension_out, 00444 long* first_node_id_out, 00445 mhdf_Status* status ); 00446 00447 hid_t mhdf_openNodeCoordsSimple( mhdf_FileHandle file_handle, mhdf_Status* status ); 00448 00449 /** \brief Write node coordinate data 00450 * 00451 * Write interleaved coordinate data for a block of nodes 00452 * 00453 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00454 * or <code>mhdf_openNodeCoords</code>. 00455 * \param offset Table row (node index) at which to start writing. 00456 * \param count Number of rows (number of nodes) to write. 00457 * \param coords Interleaved node coordinate data. 00458 * \param status Passed back status of API call. 00459 */ 00460 void mhdf_writeNodeCoords( hid_t data_handle, long offset, long count, const double* coords, mhdf_Status* status ); 00461 void mhdf_writeNodeCoordsWithOpt( hid_t data_handle, 00462 long offset, 00463 long count, 00464 const double* coords, 00465 hid_t write_prop, 00466 mhdf_Status* status ); 00467 00468 /** \brief Write node coordinate data 00469 * 00470 * Write a single coordinate value (e.g. the 'x' coordinate) for a 00471 * block of nodes. 00472 * 00473 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00474 * or <code>mhdf_openNodeCoords</code>. 00475 * \param offset Table row (node index) at which to start writing. 00476 * \param count Number of rows (number of nodes) to write. 00477 * \param dimension The coordinate to write (0->x, 1->y, ...) 00478 * \param coords Coordinate list. 00479 * \param status Passed back status of API call. 00480 */ 00481 void mhdf_writeNodeCoord( hid_t data_handle, 00482 long offset, 00483 long count, 00484 int dimension, 00485 const double* coords, 00486 mhdf_Status* status ); 00487 void mhdf_writeNodeCoordWithOpt( hid_t data_handle, 00488 long offset, 00489 long count, 00490 int dimension, 00491 const double* coords, 00492 hid_t write_prop, 00493 mhdf_Status* status ); 00494 00495 /** \brief Read node coordinate data 00496 * 00497 * Read interleaved coordinate data for a block of nodes 00498 * 00499 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00500 * or <code>mhdf_openNodeCoords</code>. 00501 * \param offset Table row (node index) at which to start reading. 00502 * \param count Number of rows (number of nodes) to read. 00503 * \param coordinates Buffer in which to write node coordinate data. 00504 * \param status Passed back status of API call. 00505 */ 00506 void mhdf_readNodeCoords( hid_t data_handle, long offset, long count, double* coordinates, mhdf_Status* status ); 00507 void mhdf_readNodeCoordsWithOpt( hid_t data_handle, 00508 long offset, 00509 long count, 00510 double* coordinates, 00511 hid_t read_prop, 00512 mhdf_Status* status ); 00513 00514 /** \brief Read node coordinate data 00515 * 00516 * Read a single coordinate value (e.g. the 'x' coordinate) for a 00517 * block of nodes. 00518 * 00519 * \param data_handle Handle returned from <code>mhdf_createNodeCoords</code> 00520 * or <code>mhdf_openNodeCoords</code>. 00521 * \param offset Table row (node index) at which to start reading. 00522 * \param count Number of rows (number of nodes) to read. 00523 * \param dimension The coordinate to read (0->x, 1->y, ...) 00524 * \param coords Buffer in which to write node coordinate data. 00525 * \param status Passed back status of API call. 00526 */ 00527 void mhdf_readNodeCoord( hid_t data_handle, 00528 long offset, 00529 long count, 00530 int dimension, 00531 double* coords, 00532 mhdf_Status* status ); 00533 void mhdf_readNodeCoordWithOpt( hid_t data_handle, 00534 long offset, 00535 long count, 00536 int dimension, 00537 double* coords, 00538 hid_t read_prop, 00539 mhdf_Status* status ); 00540 00541 /*@}*/ 00542 /** 00543 *\defgroup mhdf_conn Element connectivity data. 00544 */ 00545 /*@{*/ 00546 00547 /* Element Connectivity */ 00548 00549 /** \brief Add a new table of element data to the file. 00550 * 00551 * Add a element group to the file. 00552 * An element group is the data for a block of elements with the same 00553 * TSTT type and same number of nodes in their connectivity data. 00554 * (e.g. all the MBHEX20 elements). This function is also 00555 * used to create the groups for general polygon data and 00556 * general polyhedron data. The requirement that all elements 00557 * have the same number of nodes in their connectivity does not 00558 * apply for poly(gons|hedra). 00559 * 00560 * \param file_handle File in which to create the element type. 00561 * \param elem_handle The name to use for the element data. This 00562 * name is used as an identifier to reference the 00563 * data for this element type later. The selected 00564 * name also appears explicitly in the file and 00565 * therefore should be something 00566 * descriptive of the element type such as the 00567 * 'base type' and number of nodes (e.g. "Hex20"). 00568 * \param named_elem_type An index into the list of named element types 00569 * passed to \ref mhdf_createFile . 00570 * \param status Passed back status of API call. 00571 */ 00572 void mhdf_addElement( mhdf_FileHandle file_handle, 00573 const char* elem_handle, 00574 unsigned int named_elem_type, 00575 mhdf_Status* status ); 00576 00577 /** \brief Get the list of element groups in the file. 00578 * 00579 * Get the list of element groups in the file. 00580 * An element group is the data for a block of elements with the same 00581 * TSTT type and same number of nodes in their connectivity data. 00582 * (e.g. all the MBHEX20 elements). This function is also 00583 * used to retrieve the groups for general polygon data and 00584 * general polyhedron data. The requirement that all elements 00585 * have the same number of nodes in their connectivity does not 00586 * apply for poly(gons|hedra). 00587 * 00588 * \param file_handle The file. 00589 * \param count_out Memory location at which to store the 00590 * length of the returned array. 00591 * \param status Passed back status of API call. 00592 * \return An array of pointers to element group 00593 * names. This array is allocated as a 00594 * single memory block and should be freed 00595 * with <em>one</em> call to free(). 00596 */ 00597 char** mhdf_getElemHandles( mhdf_FileHandle file_handle, unsigned int* count_out, mhdf_Status* status ); 00598 00599 /** 00600 * \brief Get the element type name for a given element group handle. 00601 * 00602 * Fails if name is longer than <code>buf_len</code>. 00603 * 00604 * \param file_handle The file. 00605 * \param elem_handle One of the group names passed back from 00606 * \ref mhdf_getElemHandles 00607 * \param buffer A buffer to copy the name into. 00608 * \param buf_len The length of <code>buffer</code>. 00609 * \param status Passed back status of API call. 00610 */ 00611 void mhdf_getElemTypeName( mhdf_FileHandle file_handle, 00612 const char* elem_handle, 00613 char* buffer, 00614 size_t buf_len, 00615 mhdf_Status* status ); 00616 00617 /** \brief Check if an element group contains polygon or polyhedron 00618 * 00619 * Check if an element group contains general polygon or polyhedrons 00620 * rather than typically fixed-connectivity elements. 00621 * 00622 * \param file_handle The file. 00623 * \param elem_handle The element group. 00624 * \param status Passed back status of API call. 00625 * \return Zero if normal fixed-connectivity element data. Non-zero if 00626 * poly(gon/hedron) general-connectivity data. 00627 */ 00628 int mhdf_isPolyElement( mhdf_FileHandle file_handle, const char* elem_handle, mhdf_Status* status ); 00629 00630 /** \brief Create connectivity table for an element group 00631 * 00632 * Create fixed-connectivity data for an element group. 00633 * Do NOT use this function for poly(gon/hedron) data. 00634 * 00635 * \param file_handle The file. 00636 * \param elem_handle The element group. 00637 * \param num_nodes_per_elem The number of nodes in the connectivity data 00638 * for each element. 00639 * \param num_elements The number of elements to be written to the table. 00640 * \param first_elem_id_out Elements are assigned global IDs in 00641 * sequential blocks where the block is the table in 00642 * which their connectivity data is written and the 00643 * sequence is the sequence in which they are written 00644 * in that table. The global ID for the first element 00645 * in this group is passed back at this address. The 00646 * global IDs for all other elements in the table are 00647 * assigned in the sequence in which they are written 00648 * in the table. 00649 * \param status Passed back status of API call. 00650 * \return The HDF5 handle to the connectivity data. 00651 */ 00652 hid_t mhdf_createConnectivity( mhdf_FileHandle file_handle, 00653 const char* elem_handle, 00654 int num_nodes_per_elem, 00655 long num_elements, 00656 long* first_elem_id_out, 00657 mhdf_Status* status ); 00658 00659 /** \brief Open connectivity table for an element group 00660 * 00661 * Open fixed-connectivity data for an element group. 00662 * Do NOT use this function for poly(gon/hedron) data. Use 00663 * <code>mhdf_isPolyElement</code> or <code>mhdf_getTsttElemType</code> 00664 * to check if the data is poly(gon|hedron) data before calling this 00665 * function to open the data. 00666 * 00667 * \param file_handle The file. 00668 * \param elem_handle The element group. 00669 * \param num_nodes_per_elem_out Used to pass back the number of nodes 00670 * in each element. 00671 * \param num_elements_out Pass back the number of elements in the table. 00672 * \param first_elem_id_out Elements are assigned global IDs in 00673 * sequential blocks where the block is the table in 00674 * which their connectivity data is written and the 00675 * sequence is the sequence in which they are written 00676 * in that table. The global ID for the first element 00677 * in this group is passed back at this address. The 00678 * global IDs for all other elements in the table are 00679 * assigned in the sequence in which they are written 00680 * in the table. 00681 * \param status Passed back status of API call. 00682 * \return The HDF5 handle to the connectivity data. 00683 */ 00684 hid_t mhdf_openConnectivity( mhdf_FileHandle file_handle, 00685 const char* elem_handle, 00686 int* num_nodes_per_elem_out, 00687 long* num_elements_out, 00688 long* first_elem_id_out, 00689 mhdf_Status* status ); 00690 00691 hid_t mhdf_openConnectivitySimple( mhdf_FileHandle file_handle, const char* elem_handle, mhdf_Status* status ); 00692 00693 /** \brief Write element coordinate data 00694 * 00695 * Write interleaved fixed-connectivity element data for a block of elements. 00696 * Note: Do not use this for polygon or polyhedron data. 00697 * 00698 * \param data_handle Handle returned from <code>mhdf_createConnectivity</code> 00699 * or <code>mhdf_openConnectivity</code>. 00700 * \param offset Table row (element index) at which to start writing. 00701 * \param count Number of rows (number of elements) to write. 00702 * \param hdf_integer_type The type of the integer data in node_id_list. 00703 * Typically <code>H5T_NATIVE_INT</code> or 00704 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00705 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00706 * \param node_id_list Interleaved connectivity data specified as global node IDs. 00707 * \param status Passed back status of API call. 00708 */ 00709 void mhdf_writeConnectivity( hid_t data_handle, 00710 long offset, 00711 long count, 00712 hid_t hdf_integer_type, 00713 const void* node_id_list, 00714 mhdf_Status* status ); 00715 void mhdf_writeConnectivityWithOpt( hid_t data_handle, 00716 long offset, 00717 long count, 00718 hid_t hdf_integer_type, 00719 const void* node_id_list, 00720 hid_t write_prop, 00721 mhdf_Status* status ); 00722 00723 /** \brief Read element coordinate data 00724 * 00725 * Read interleaved fixed-connectivity element data for a block of elements. 00726 * Note: Do not use this for polygon or polyhedron data. 00727 * 00728 * \param data_handle Handle returned from <code>mhdf_createConnectivity</code> 00729 * or <code>mhdf_openConnectivity</code>. 00730 * \param offset Table row (element index) at which to start read. 00731 * \param count Number of rows (number of elements) to read. 00732 * \param hdf_integer_type The type of the integer data in node_id_list. 00733 * Typically <code>H5T_NATIVE_INT</code> or 00734 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00735 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00736 * \param node_id_list Pointer to memory at which to write interleaved 00737 * connectivity data specified as global node IDs. 00738 * \param status Passed back status of API call. 00739 */ 00740 void mhdf_readConnectivity( hid_t data_handle, 00741 long offset, 00742 long count, 00743 hid_t hdf_integer_type, 00744 void* node_id_list, 00745 mhdf_Status* status ); 00746 void mhdf_readConnectivityWithOpt( hid_t data_handle, 00747 long offset, 00748 long count, 00749 hid_t hdf_integer_type, 00750 void* node_id_list, 00751 hid_t read_prop, 00752 mhdf_Status* status ); 00753 00754 /* Poly(gon|hedra) */ 00755 00756 /** \brief Create a new table for polygon or polyhedron connectivity data. 00757 * 00758 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00759 * One list is the concatenation of the the connectivity data for 00760 * all the polys in the group. The other contains one value per 00761 * poly where that value is the index of the last entry in the 00762 * connectivity of the corresponding poly. The ID 00763 * list for polygons contains global node IDs. The ID list for polyhedra 00764 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00765 * elements.) 00766 * 00767 * \param file_handle The file to write. 00768 * \param elem_handle The element group. 00769 * \param num_poly The total number number of polygons or polyhedra to 00770 * be written in the table. 00771 * \param data_list_length The total number of values to be written to the 00772 * table (the number of polys plus the sum of the number 00773 * of entities in each poly's connectivity data.) 00774 * \param first_id_out Elements are assigned global IDs in 00775 * sequential blocks where the block is the table in 00776 * which their connectivity data is written and the 00777 * sequence is the sequence in which they are written 00778 * in that table. The global ID for the first element 00779 * in this group is passed back at this address. The 00780 * global IDs for all other elements in the table are 00781 * assigned in the sequence in which they are written 00782 * in the table. 00783 * \param idx_and_id_handles_out The handles for the index list and 00784 * connectivity list, respectively. 00785 * \param status Passed back status of API call. 00786 */ 00787 void mhdf_createPolyConnectivity( mhdf_FileHandle file_handle, 00788 const char* elem_handle, 00789 long num_poly, 00790 long data_list_length, 00791 long* first_id_out, 00792 hid_t idx_and_id_handles_out[2], 00793 mhdf_Status* status ); 00794 00795 /** \brief Open a table of polygon or polyhedron connectivity data. 00796 * 00797 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00798 * One list is the concatenation of the the connectivity data for 00799 * all the polys in the group. The other contains one value per 00800 * poly where that value is the index of the last entry in the 00801 * connectivity of the corresponding poly. The ID 00802 * list for polygons contains global node IDs. The ID list for polyhedra 00803 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00804 * elements.) 00805 * 00806 * \param file_handle The file to write. 00807 * \param elem_handle The element group. 00808 * \param num_poly_out The total number number of polygons or polyhedra to 00809 * be written in the table. 00810 * \param data_list_length_out The total number of values to be written to the 00811 * table (the number of polys plus the sum of the number 00812 * of entities in each poly's connectivity data.) 00813 * \param first_id_out Elements are assigned global IDs in 00814 * sequential blocks where the block is the table in 00815 * which their connectivity data is written and the 00816 * sequence is the sequence in which they are written 00817 * in that table. The global ID for the first element 00818 * in this group is passed back at this address. The 00819 * global IDs for all other elements in the table are 00820 * assigned in the sequence in which they are written 00821 * in the table. 00822 * \param idx_and_id_handles_out The handles for the index list and 00823 * connectivity list, respectively. 00824 * \param status Passed back status of API call. 00825 */ 00826 void mhdf_openPolyConnectivity( mhdf_FileHandle file_handle, 00827 const char* elem_handle, 00828 long* num_poly_out, 00829 long* data_list_length_out, 00830 long* first_id_out, 00831 hid_t idx_and_id_handles_out[2], 00832 mhdf_Status* status ); 00833 00834 /** \brief Write polygon or polyhedron index data. 00835 * 00836 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00837 * One list is the concatenation of the the connectivity data for 00838 * all the polys in the group. The other contains one value per 00839 * poly where that value is the index of the last entry in the 00840 * connectivity of the corresponding poly. The ID 00841 * list for polygons contains global node IDs. The ID list for polyhedra 00842 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00843 * elements.) 00844 * 00845 * This function writes the index list. 00846 * 00847 * \param poly_handle The handle returned from 00848 * <code>mhdf_createPolyConnectivity</code> or 00849 * <code>mhdf_openPolyConnectivity</code>. 00850 * \param offset The offset in the table at which to write. The 00851 * offset is in terms of the integer values in the table, 00852 * not the count of polys. 00853 * \param count The size of the integer list to write. 00854 * \param hdf_integer_type The type of the integer data in <code>id_list</code>. 00855 * Typically <code>H5T_NATIVE_INT</code> or 00856 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00857 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00858 * \param index_list The index list for the polys. 00859 * \param status Passed back status of API call. 00860 */ 00861 void mhdf_writePolyConnIndices( hid_t poly_handle, 00862 long offset, 00863 long count, 00864 hid_t hdf_integer_type, 00865 const void* index_list, 00866 mhdf_Status* status ); 00867 void mhdf_writePolyConnIndicesWithOpt( hid_t poly_handle, 00868 long offset, 00869 long count, 00870 hid_t hdf_integer_type, 00871 const void* index_list, 00872 hid_t write_prop, 00873 mhdf_Status* status ); 00874 00875 /** \brief Write polygon or polyhedron connectivity data. 00876 * 00877 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00878 * One list is the concatenation of the the connectivity data for 00879 * all the polys in the group. The other contains one value per 00880 * poly where that value is the index of the last entry in the 00881 * connectivity of the corresponding poly. The ID 00882 * list for polygons contains global node IDs. The ID list for polyhedra 00883 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00884 * elements.) 00885 * 00886 * This function writes the connectivity/ID list. 00887 * 00888 * \param poly_handle The handle returned from 00889 * <code>mhdf_createPolyConnectivity</code> or 00890 * <code>mhdf_openPolyConnectivity</code>. 00891 * \param offset The offset in the table at which to write. The 00892 * offset is in terms of the integer values in the table, 00893 * not the count of polys. 00894 * \param count The size of the integer list to write. 00895 * \param hdf_integer_type The type of the integer data in <code>id_list</code>. 00896 * Typically <code>H5T_NATIVE_INT</code> or 00897 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00898 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00899 * \param id_list The count/global ID list specifying the connectivity 00900 * of the polys. 00901 * \param status Passed back status of API call. 00902 */ 00903 void mhdf_writePolyConnIDs( hid_t poly_handle, 00904 long offset, 00905 long count, 00906 hid_t hdf_integer_type, 00907 const void* id_list, 00908 mhdf_Status* status ); 00909 void mhdf_writePolyConnIDsWithOpt( hid_t poly_handle, 00910 long offset, 00911 long count, 00912 hid_t hdf_integer_type, 00913 const void* id_list, 00914 hid_t write_prop, 00915 mhdf_Status* status ); 00916 00917 /** \brief Read polygon or polyhedron index data. 00918 * 00919 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00920 * One list is the concatenation of the the connectivity data for 00921 * all the polys in the group. The other contains one value per 00922 * poly where that value is the index of the last entry in the 00923 * connectivity of the corresponding poly. The ID 00924 * list for polygons contains global node IDs. The ID list for polyhedra 00925 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00926 * elements.) 00927 * 00928 * \param poly_handle The handle returned from 00929 * <code>mhdf_createPolyConnectivity</code> or 00930 * <code>mhdf_openPolyConnectivity</code>. 00931 * \param offset The offset in the table at which to read. The 00932 * offset is in terms of the integer values in the table, 00933 * not the count of polys. 00934 * \param count The size of the integer list to read. 00935 * \param hdf_integer_type The type of the integer data as written into memory. 00936 * Typically <code>H5T_NATIVE_INT</code> or 00937 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00938 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00939 * \param index_list The memory location at which to write the indices. 00940 * \param status Passed back status of API call. 00941 */ 00942 void mhdf_readPolyConnIndices( hid_t poly_handle, 00943 long offset, 00944 long count, 00945 hid_t hdf_integer_type, 00946 void* index_list, 00947 mhdf_Status* status ); 00948 void mhdf_readPolyConnIndicesWithOpt( hid_t poly_handle, 00949 long offset, 00950 long count, 00951 hid_t hdf_integer_type, 00952 void* index_list, 00953 hid_t read_prop, 00954 mhdf_Status* status ); 00955 00956 /** \brief Read polygon or polyhedron connectivity data. 00957 * 00958 * Poly (polygon or polyhedron) connectivity is stored as two lists. 00959 * One list is the concatenation of the the connectivity data for 00960 * all the polys in the group. The other contains one value per 00961 * poly where that value is the index of the last entry in the 00962 * connectivity of the corresponding poly. The ID 00963 * list for polygons contains global node IDs. The ID list for polyhedra 00964 * contains the global IDs of faces (either polygons or 2D fixed-connectivity 00965 * elements.) 00966 * 00967 * \param poly_handle The handle returned from 00968 * <code>mhdf_createPolyConnectivity</code> or 00969 * <code>mhdf_openPolyConnectivity</code>. 00970 * \param offset The offset in the table at which to read. The 00971 * offset is in terms of the integer values in the table, 00972 * not the count of polys. 00973 * \param count The size of the integer list to read. 00974 * \param hdf_integer_type The type of the integer data as written into memory. 00975 * Typically <code>H5T_NATIVE_INT</code> or 00976 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 00977 * The HDF class of this type object <em>must</em> be H5T_INTEGER 00978 * \param id_list The memory location at which to write the connectivity data. 00979 * \param status Passed back status of API call. 00980 */ 00981 void mhdf_readPolyConnIDs( hid_t poly_handle, 00982 long offset, 00983 long count, 00984 hid_t hdf_integer_type, 00985 void* id_list, 00986 mhdf_Status* status ); 00987 void mhdf_readPolyConnIDsWithOpt( hid_t poly_handle, 00988 long offset, 00989 long count, 00990 hid_t hdf_integer_type, 00991 void* id_list, 00992 hid_t read_prop, 00993 mhdf_Status* status ); 00994 /*@}*/ 00995 /** 00996 *\defgroup mhdf_adj Adjacency data. 00997 * 00998 * Adjacency data is formated as a sequence of integer groups where 00999 * the first entry in each group is the ID of the element for which 01000 * adjacencies are being specified, the second value is the count of 01001 * adjacent entities, and the remainder of the group is the list of 01002 * IDs of the adjacent entities. 01003 */ 01004 /*@{*/ 01005 01006 /** \brief Create adjacency data table for nodes, elements, polys, etc. 01007 * 01008 * Create file object for adjacency data for a nodes or a specified 01009 * element group. 01010 * 01011 * Adjacency data is formated as a sequence of integer groups where 01012 * the first entry in each group is the ID of the element for which 01013 * adjacencies are being specified, the second value is the count of 01014 * adjacent entities, and the remainder of the group is the list of 01015 * IDs of the adjacent entities. 01016 * 01017 * \param file_handle The file. 01018 * \param elem_handle The element group (or the result of 01019 * <code>mhdf_node_type_handle</code> for nodes) for 01020 * which the adjacency data is to be specified. 01021 * \param adj_list_size The total number of integer values contained 01022 * in the adjacency data for the specified element group. 01023 * \param status Passed back status of API call. 01024 * \return The HDF5 handle to the connectivity data. 01025 */ 01026 hid_t mhdf_createAdjacency( mhdf_FileHandle file_handle, 01027 const char* elem_handle, 01028 long adj_list_size, 01029 mhdf_Status* status ); 01030 01031 /** \brief Check if adjacency data is present in the file for the specified 01032 * element group. 01033 * 01034 * \param file The file. 01035 * \param elem_handle A handle to an element group. 01036 * \param status Passed back status of API call. 01037 */ 01038 int mhdf_haveAdjacency( mhdf_FileHandle file, const char* elem_handle, mhdf_Status* status ); 01039 01040 /** \brief Open adjacency data table for nodes, elements, polys, etc. 01041 * 01042 * Open the file object containing adjacency data for a nodes or a specified 01043 * element group. 01044 * 01045 * Adjacency data is formated as a sequence of integer groups where 01046 * the first entry in each group is the ID of the element for which 01047 * adjacencies are being specified, the second value is the count of 01048 * adjacent entities, and the remainder of the group is the list of 01049 * IDs of the adjacent entities. 01050 * 01051 * \param file_handle The file. 01052 * \param elem_handle The element group (or the result of 01053 * <code>mhdf_node_type_handle</code> for nodes) for 01054 * which the adjacency data is to be specified. 01055 * \param adj_list_size The total number of integer values contained 01056 * in the adjacency data for the specified element group. 01057 * \param status Passed back status of API call. 01058 * \return The HDF5 handle to the connectivity data. 01059 */ 01060 hid_t mhdf_openAdjacency( mhdf_FileHandle file_handle, 01061 const char* elem_handle, 01062 long* adj_list_size, 01063 mhdf_Status* status ); 01064 01065 /** \brief Write node/element adjacency data 01066 * 01067 * Write adjacency data. 01068 * 01069 * Adjacency data is formated as a sequence of integer groups where 01070 * the first entry in each group is the ID of the element for which 01071 * adjacencies are being specified, the second value is the count of 01072 * adjacent entities, and the remainder of the group is the list of 01073 * IDs of the adjacent entities. 01074 * 01075 * \param data_handle Handle returned from <code>mhdf_createAdjacency</code> 01076 * or <code>mhdf_openAdjacency</code>. 01077 * \param offset List position at which to start writing. Offset is 01078 * from the count if integer values written, NOT a count 01079 * of the number of elements for which adjacency data 01080 * is written. 01081 * \param count Number of integer values to write. 01082 * \param hdf_integer_type The type of the integer data in <code>adj_list_data</code>. 01083 * Typically <code>H5T_NATIVE_INT</code> or 01084 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01085 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01086 * \param adj_list_data Adjacency data to write. 01087 * \param status Passed back status of API call. 01088 */ 01089 void mhdf_writeAdjacency( hid_t data_handle, 01090 long offset, 01091 long count, 01092 hid_t hdf_integer_type, 01093 const void* adj_list_data, 01094 mhdf_Status* status ); 01095 void mhdf_writeAdjacencyWithOpt( hid_t data_handle, 01096 long offset, 01097 long count, 01098 hid_t hdf_integer_type, 01099 const void* adj_list_data, 01100 hid_t write_prop, 01101 mhdf_Status* status ); 01102 01103 /** \brief Read node/element adjacency data 01104 * 01105 * Read adjacency data. 01106 * 01107 * Adjacency data is formated as a sequence of integer groups where 01108 * the first entry in each group is the ID of the element for which 01109 * adjacencies are being specified, the second value is the count of 01110 * adjacent entities, and the remainder of the group is the list of 01111 * IDs of the adjacent entities. 01112 * 01113 * \param data_handle Handle returned from <code>mhdf_createAdjacency</code> 01114 * or <code>mhdf_openAdjacency</code>. 01115 * \param offset List position at which to start reading. Offset is 01116 * from the count if integer values written, NOT a count 01117 * of the number of elements for which adjacency data 01118 * is written. 01119 * \param count Number of integer values to reading. 01120 * \param hdf_integer_type The type of the integer data in <code>adj_list_data_out</code>. 01121 * Typically <code>H5T_NATIVE_INT</code> or 01122 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01123 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01124 * \param adj_list_data_out Pointer to memory at which to write adjacency data. 01125 * \param status Passed back status of API call. 01126 */ 01127 void mhdf_readAdjacency( hid_t data_handle, 01128 long offset, 01129 long count, 01130 hid_t hdf_integer_type, 01131 void* adj_list_data_out, 01132 mhdf_Status* status ); 01133 void mhdf_readAdjacencyWithOpt( hid_t data_handle, 01134 long offset, 01135 long count, 01136 hid_t hdf_integer_type, 01137 void* adj_list_data_out, 01138 hid_t read_prop, 01139 mhdf_Status* status ); 01140 01141 /*@}*/ 01142 01143 /** 01144 *\defgroup mhdf_set Meshset data. 01145 * 01146 * Meshset data is divided into three groups of data. The set-list/meta-information table, 01147 * the set contents table and the set children table. Each is written and read independently. 01148 * 01149 * The set list table contains one row for each set. Each row contains four values: 01150 * {content list end index, child list end index, parent list end index, and flags}. The flags 01151 * value is a collection of bits with 01152 * values defined in \ref mhdf_set_flag . The all the flags except \ref mhdf_SET_RANGE_BIT are 01153 * saved properties of the mesh data and are not relevant to the actual file in any way. The 01154 * \ref mhdf_SET_RANGE_BIT flag is a toggle for how the meshset contents (not children) are saved. 01155 * It is an internal property of the file format and should not be passed on to the mesh database. 01156 * The content list end index and child list end index are the indices of the last entry for the 01157 * set in the contents and children tables respectively. In the case where a set has either no 01158 * children or no contents, the last index of should be the same as the last index of the previous 01159 * set in the table, or -1 for the first set in the table. Thus the first index is always one 01160 * greater than the last index of the previous set. If the first index, calculated as one greater 01161 * that the last index of the previous set is greater than the last index of the current set, then 01162 * there are no values in the corresponding contents or children table for that set. 01163 * 01164 * The set contents table is a vector of integer global IDs that is the concatenation of the contents 01165 * data for all of the mesh sets. The values are stored corresponding to the order of the sets 01166 * in the set list table. Depending on the value of \ref mhdf_SET_RANGE_BIT in the flags field of 01167 * the set list table, the contents for a specific set may be stored in one of two formats. If the 01168 * flag is set, the contents list is a list of pairs where each pair is a starting global Id and a 01169 * count. For each pair, the set contains the range of global Ids beginning at the start value. 01170 * If the \ref mhdf_SET_RANGE_BIT flag is not set, the meshset contents are a simple list of global Ids. 01171 * 01172 * The meshset child table is a vector of integer global IDs. It is a concatenation of the child 01173 * lists for all the mesh sets, in the order the sets occur in the meshset list table. The values 01174 * are always simple lists. The child table may never contain ranges of IDs. 01175 */ 01176 /*@{*/ 01177 01178 /** 01179 *\defgroup mhdf_set_flag Set flag bits 01180 */ 01181 /*@{*/ 01182 01183 /** \brief Make entities in set aware of owning set (MOAB-specific?)*/ 01184 #define mhdf_SET_OWNER_BIT 0x1 01185 /** \brief Set cannot contain duplicates */ 01186 #define mhdf_SET_UNIQUE_BIT 0x2 01187 /** \brief Set order is preserved */ 01188 #define mhdf_SET_ORDER_BIT 0x4 01189 01190 /** \brief The bit specifying set storage format. 01191 * 01192 * If this bit is set, then the contents of a set (not the children) 01193 * is written as set of ranges, where each range is of the form 01194 * {global start id, count}. For such a range, the set contains the 01195 * <code>count</code> entities with sequential global IDs beginning 01196 * with the specified start ID. If this bit is not set in the set flags, 01197 * the contents of the set are stored as a simple list of global IDs. 01198 */ 01199 #define mhdf_SET_RANGE_BIT 0x8 01200 01201 /*@}*/ 01202 01203 /** \brief Create table holding list of meshsets and their properties. 01204 * 01205 * The set table contains description of sets, but not contents or 01206 * children. The table is a <code>n x 4</code> matrix of values. 01207 * One row for each of <code>n</code> sets. Each row contains the end index 01208 * for the set in the contents table, the end index for the set in the children 01209 * table, the end index for the set in the parents table, and the set flags, 01210 * respectively. The \ref mhdf_SET_RANGE_BIT 01211 * bit in the flags specifies the format of the contents list for each set. 01212 * See a description of the \ref mhdf_SET_RANGE_BIT flag for a description 01213 * of the two possible data formats. The index values in the first two columns 01214 * of the table are the index of the <em>last</em> value for the set in the corresponding 01215 * contents and children lists. The first index is always one greater than the last index 01216 * for the previous set in the table. The first index of the first set in the table is 01217 * implicitly zero. A special value of -1 in the appropriate column should be used to 01218 * indicate that the first set contains no contents or has no children. For any other set, 01219 * if the last index for the set is the same as that of the previous set, it has no data 01220 * in the corresponding list. 01221 * 01222 *\param file_handle The file. 01223 *\param num_sets The number of sets in the table. 01224 *\param first_set_id_out The global ID that will be assigned to the first 01225 * set in the table. All subsequent sets in the table 01226 * will be assigned sequential global IDs. 01227 * \param status Passed back status of API call. 01228 *\return The handle to the set meta-data table. 01229 */ 01230 hid_t mhdf_createSetMeta( mhdf_FileHandle file_handle, long num_sets, long* first_set_id_out, mhdf_Status* status ); 01231 01232 /** \brief Check if file contains any sets 01233 * 01234 *\param file The file. 01235 *\param have_set_data_out If non-null set to 1 if file contains table 01236 * of set contents, zero otherwise. 01237 *\param have_set_child_out If non-null set to 1 if file contains table 01238 * of set children, zero otherwise. 01239 *\param have_set_parents_out If non-null set to 1 if file contains table 01240 * of set parents, zero otherwise. 01241 * \param status Passed back status of API call. 01242 *\return Zero if the file does not contain any sets, one if it does. 01243 */ 01244 int mhdf_haveSets( mhdf_FileHandle file, 01245 int* have_set_data_out, 01246 int* have_set_child_out, 01247 int* have_set_parents_out, 01248 mhdf_Status* status ); 01249 01250 /** \brief Open table holding list of meshsets and their properties. 01251 * 01252 * Open set list. 01253 * See \ref mhdf_createSetMeta or \ref mhdf_set for a description of this data. 01254 * 01255 *\param file_handle The file. 01256 *\param num_sets_out The number of sets in the table. 01257 *\param first_set_id_out The global ID that will of the first 01258 * set in the table. All subsequent sets in the table 01259 * have sequential global IDs. 01260 * \param status Passed back status of API call. 01261 *\return The handle to the set meta-data table. 01262 */ 01263 hid_t mhdf_openSetMeta( mhdf_FileHandle file_handle, long* num_sets_out, long* first_set_id_out, mhdf_Status* status ); 01264 01265 hid_t mhdf_openSetMetaSimple( mhdf_FileHandle file_handle, mhdf_Status* status ); 01266 01267 /** \brief Read list of sets and meta-information about sets. 01268 * 01269 * Read set descriptions. See \ref mhdf_createSetMeta or \ref mhdf_set 01270 * for a description of this data. 01271 * 01272 *\param data_handle The handle returned from \ref mhdf_createSetMeta or 01273 * \ref mhdf_openSetMeta. 01274 *\param offset The offset (set index) to begin reading at. 01275 *\param count The number of rows (sets, integer triples) to read. 01276 *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>. 01277 * Typically <code>H5T_NATIVE_INT</code> or 01278 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01279 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01280 * \param status Passed back status of API call. 01281 *\param set_desc_data The memory location at which to write the data. 01282 */ 01283 void mhdf_readSetMeta( hid_t data_handle, 01284 long offset, 01285 long count, 01286 hid_t hdf_integer_type, 01287 void* set_desc_data, 01288 mhdf_Status* status ); 01289 void mhdf_readSetMetaWithOpt( hid_t data_handle, 01290 long offset, 01291 long count, 01292 hid_t hdf_integer_type, 01293 void* set_desc_data, 01294 hid_t read_prop, 01295 mhdf_Status* status ); 01296 01297 /** \brief Read only the flags portion of the set description table 01298 * 01299 * Read flags for each set from the set description table. 01300 * See \ref mhdf_createSetMeta for a description of this data. 01301 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01302 *\param offset The offset (set index) at which to begin reading. 01303 *\param count The number of values (number of sets) to read. 01304 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01305 *\param set_flag_data Array of integers. 01306 *\param status Location at which to store status of API call. 01307 */ 01308 void mhdf_readSetFlags( hid_t data_handle, 01309 long offset, 01310 long count, 01311 hid_t hdf_integer_type, 01312 void* set_flag_data, 01313 mhdf_Status* status ); 01314 void mhdf_readSetFlagsWithOpt( hid_t data_handle, 01315 long offset, 01316 long count, 01317 hid_t hdf_integer_type, 01318 void* set_flag_data, 01319 hid_t read_prop, 01320 mhdf_Status* status ); 01321 01322 /** \brief Read only the content end indices portion of the set description table 01323 * 01324 * For each set, read the last index of that set's data in the set 01325 * contents table. 01326 * 01327 * NOTE: This is a signed value. Any sets w/out contents that occur 01328 * first in the list will have an end index of -1. 01329 * 01330 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01331 *\param offset The offset (set index) at which to begin reading. 01332 *\param count The number of values (number of sets) to read. 01333 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01334 *\param end_indices_out Array of indices. 01335 *\param status Location at which to store status of API call. 01336 */ 01337 void mhdf_readSetContentEndIndices( hid_t data_handle, 01338 long offset, 01339 long count, 01340 hid_t hdf_integer_type, 01341 void* end_indices_out, 01342 mhdf_Status* status ); 01343 void mhdf_readSetContentEndIndicesWithOpt( hid_t data_handle, 01344 long offset, 01345 long count, 01346 hid_t hdf_integer_type, 01347 void* end_indices_out, 01348 hid_t read_prop, 01349 mhdf_Status* status ); 01350 01351 /** \brief Read only the child end indices portion of the set description table 01352 * 01353 * For each set, read the last index of that set's data in the set 01354 * children table. 01355 * 01356 * NOTE: This is a signed value. Any sets w/out contents that occur 01357 * first in the list will have an end index of -1. 01358 * 01359 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01360 *\param offset The offset (set index) at which to begin reading. 01361 *\param count The number of values (number of sets) to read. 01362 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01363 *\param end_indices_out Array of indices. 01364 *\param status Location at which to store status of API call. 01365 */ 01366 void mhdf_readSetChildEndIndices( hid_t data_handle, 01367 long offset, 01368 long count, 01369 hid_t hdf_integer_type, 01370 void* end_indices_out, 01371 mhdf_Status* status ); 01372 void mhdf_readSetChildEndIndicesWithOpt( hid_t data_handle, 01373 long offset, 01374 long count, 01375 hid_t hdf_integer_type, 01376 void* end_indices_out, 01377 hid_t read_prop, 01378 mhdf_Status* status ); 01379 01380 /** \brief Read only the parent end indices portion of the set description table 01381 * 01382 * For each set, read the last index of that set's data in the set 01383 * parents table. 01384 * 01385 * NOTE: This is a signed value. Any sets w/out contents that occur 01386 * first in the list will have an end index of -1. 01387 * 01388 *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta 01389 *\param offset The offset (set index) at which to begin reading. 01390 *\param count The number of values (number of sets) to read. 01391 *\param hdf_integer_type The integer type of the input array 'set_flag_data'. 01392 *\param end_indices_out Array of indices. 01393 *\param status Location at which to store status of API call. 01394 */ 01395 void mhdf_readSetParentEndIndices( hid_t data_handle, 01396 long offset, 01397 long count, 01398 hid_t hdf_integer_type, 01399 void* end_indices_out, 01400 mhdf_Status* status ); 01401 void mhdf_readSetParentEndIndicesWithOpt( hid_t data_handle, 01402 long offset, 01403 long count, 01404 hid_t hdf_integer_type, 01405 void* end_indices_out, 01406 hid_t read_prop, 01407 mhdf_Status* status ); 01408 01409 /** \brief Write list of sets and meta-information about sets. 01410 * 01411 * Write set descriptions. See \ref mhdf_createSetMeta or \ref mhdf_set for a 01412 * description of the data format. 01413 * 01414 *\param data_handle The handle returned from \ref mhdf_createSetMeta or 01415 * \ref mhdf_openSetMeta. 01416 *\param offset The offset (set index) to begin writing at. 01417 *\param count The number of rows (sets, integer triples) to write. 01418 *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>. 01419 * Typically <code>H5T_NATIVE_INT</code> or 01420 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01421 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01422 *\param set_desc_data The data to write. 01423 * \param status Passed back status of API call. 01424 */ 01425 void mhdf_writeSetMeta( hid_t data_handle, 01426 long offset, 01427 long count, 01428 hid_t hdf_integer_type, 01429 const void* set_desc_data, 01430 mhdf_Status* status ); 01431 void mhdf_writeSetMetaWithOpt( hid_t data_handle, 01432 long offset, 01433 long count, 01434 hid_t hdf_integer_type, 01435 const void* set_desc_data, 01436 hid_t write_prop, 01437 mhdf_Status* status ); 01438 01439 /** \brief Create file object to hold list of meshset contents. 01440 * 01441 * Create set contents data object. 01442 * The format of this data is a vector of integer values which is the 01443 * concatenation of the contents list for all the meshsets. The length 01444 * and format of the data for each set is stored in the set meta table. 01445 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01446 * description of that data. 01447 * 01448 *\param file_handle The file. 01449 *\param data_list_size The total length (number of integer values) to 01450 * be written for all the sets. 01451 *\param status Passed back status of API call. 01452 *\return A handle to the table. 01453 */ 01454 hid_t mhdf_createSetData( mhdf_FileHandle file_handle, long data_list_size, mhdf_Status* status ); 01455 01456 /** \brief Open the file object for the meshset contents. 01457 * 01458 * Open set contents data object. 01459 * The format of this data is a vector of integer values which is the 01460 * concatenation of the contents list for all the meshsets. The length 01461 * and format of the data for each set is stored in the set meta table. 01462 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01463 * description of that data. 01464 * 01465 *\param file_handle The file. 01466 *\param data_list_size_out The length of the table. 01467 *\param status Passed back status of API call. 01468 *\return A handle to the table. 01469 */ 01470 hid_t mhdf_openSetData( mhdf_FileHandle file_handle, long* data_list_size_out, mhdf_Status* status ); 01471 01472 /** \brief Write set contents. 01473 * 01474 * Write data specifying entities contained in sets. 01475 * The format of this data is a vector of integer values which is the 01476 * concatenation of the contents list for all the meshsets. The length 01477 * and format of the data for each set is stored in the set meta table. 01478 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01479 * description of that data. 01480 * 01481 *\param set_handle The handle returned from \ref mhdf_createSetData 01482 * or \ref mhdf_openSetData . 01483 *\param offset The position at which to write into the integer vector. 01484 *\param count The number of values to write into the data vector. 01485 *\param hdf_integer_type The type of the integer data in <code>set_data</code>. 01486 * Typically <code>H5T_NATIVE_INT</code> or 01487 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01488 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01489 *\param set_data The data to write. 01490 *\param status Passed back status of API call. 01491 */ 01492 void mhdf_writeSetData( hid_t set_handle, 01493 long offset, 01494 long count, 01495 hid_t hdf_integer_type, 01496 const void* set_data, 01497 mhdf_Status* status ); 01498 void mhdf_writeSetDataWithOpt( hid_t set_handle, 01499 long offset, 01500 long count, 01501 hid_t hdf_integer_type, 01502 const void* set_data, 01503 hid_t write_prop, 01504 mhdf_Status* status ); 01505 01506 /** \brief Read set contents. 01507 * 01508 * Read data specifying entities contained in sets. 01509 * The format of this data is a vector of integer values which is the 01510 * concatenation of the contents list for all the meshsets. The length 01511 * and format of the data for each set is stored in the set meta table. 01512 * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 01513 * description of that data. 01514 * 01515 *\param set_handle The handle returned from \ref mhdf_createSetData 01516 * or \ref mhdf_openSetData . 01517 *\param offset The position at which to read from the integer vector. 01518 *\param count The number of values to read from the data vector. 01519 *\param hdf_integer_type The type of the integer data in <code>set_data</code>. 01520 * Typically <code>H5T_NATIVE_INT</code> or 01521 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01522 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01523 *\param set_data A pointer to memory at which to store the read data. 01524 *\param status Passed back status of API call. 01525 */ 01526 void mhdf_readSetData( hid_t set_handle, 01527 long offset, 01528 long count, 01529 hid_t hdf_integer_type, 01530 void* set_data, 01531 mhdf_Status* status ); 01532 void mhdf_readSetDataWithOpt( hid_t set_handle, 01533 long offset, 01534 long count, 01535 hid_t hdf_integer_type, 01536 void* set_data, 01537 hid_t read_prop, 01538 mhdf_Status* status ); 01539 01540 /** \brief Create file object for storing the set child list 01541 * 01542 * Create a data group for the list of set children. 01543 * The format of this data is the concatenation of the lists of 01544 * global IDs of child sets for each set. The order of the sets and 01545 * the number of children for each set is contained in the set meta table. 01546 * (See \ref mhdf_createSetMeta ). 01547 * 01548 *\param file_handle The file 01549 *\param child_list_size The total length of the data (the sum of the 01550 * number of children for each set.) 01551 *\param status Passed back status of API call. 01552 *\return A handle to the data object in the file. 01553 */ 01554 hid_t mhdf_createSetChildren( mhdf_FileHandle file_handle, long child_list_size, mhdf_Status* status ); 01555 01556 /** \brief Open the file object containing the set child list 01557 * 01558 * Open the data group containing the list of set children. 01559 * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 01560 * a description of this data. 01561 * 01562 *\param file_handle The file 01563 *\param child_list_size The total length of the data (the sum of the 01564 * number of children for each set.) 01565 *\param status Passed back status of API call. 01566 *\return A handle to the data object in the file. 01567 */ 01568 hid_t mhdf_openSetChildren( mhdf_FileHandle file_handle, long* child_list_size, mhdf_Status* status ); 01569 01570 /** \brief Create file object for storing the set parent list 01571 * 01572 * Create a data group for the list of set parents. 01573 * The format of this data is the concatenation of the lists of 01574 * global IDs of parent sets for each set. The order of the sets and 01575 * the number of parents for each set is contained in the set meta table. 01576 * (See \ref mhdf_createSetMeta ). 01577 * 01578 *\param file_handle The file 01579 *\param parent_list_size The total length of the data (the sum of the 01580 * number of parents for each set.) 01581 *\param status Passed back status of API call. 01582 *\return A handle to the data object in the file. 01583 */ 01584 hid_t mhdf_createSetParents( mhdf_FileHandle file_handle, long parent_list_size, mhdf_Status* status ); 01585 01586 /** \brief Open the file object containing the set parent list 01587 * 01588 * Open the data group containing the list of set parents. 01589 * See \ref mhdf_createSetParents and \ref mhdf_createSetMeta for 01590 * a description of this data. 01591 * 01592 *\param file_handle The file 01593 *\param parent_list_size The total length of the data (the sum of the 01594 * number of parents for each set.) 01595 *\param status Passed back status of API call. 01596 *\return A handle to the data object in the file. 01597 */ 01598 hid_t mhdf_openSetParents( mhdf_FileHandle file_handle, long* parent_list_size, mhdf_Status* status ); 01599 01600 /** \brief Write set parent/child list 01601 * 01602 * Write the list of parent or child IDs for sets. 01603 * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 01604 * a description of this data. 01605 * 01606 *\param data_handle The value returned from \ref mhdf_createSetChildren 01607 * or \ref mhdf_openSetChildren. 01608 *\param offset The offset into the list of global IDs. 01609 *\param count The number of global IDs to write. 01610 *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>. 01611 * Typically <code>H5T_NATIVE_INT</code> or 01612 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01613 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01614 *\param id_list The data to write. 01615 *\param status Passed back status of API call. 01616 */ 01617 void mhdf_writeSetParentsChildren( hid_t data_handle, 01618 long offset, 01619 long count, 01620 hid_t hdf_integer_type, 01621 const void* id_list, 01622 mhdf_Status* status ); 01623 void mhdf_writeSetParentsChildrenWithOpt( hid_t data_handle, 01624 long offset, 01625 long count, 01626 hid_t hdf_integer_type, 01627 const void* id_list, 01628 hid_t write_prop, 01629 mhdf_Status* status ); 01630 01631 /** \brief Read set parent/child list 01632 * 01633 * Read from the list of parent or child IDs for sets. 01634 * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 01635 * a description of this data. 01636 * 01637 *\param data_handle The value returned from \ref mhdf_createSetChildren 01638 * or \ref mhdf_openSetChildren. 01639 *\param offset The offset into the list of global IDs. 01640 *\param count The number of global IDs to read. 01641 *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>. 01642 * Typically <code>H5T_NATIVE_INT</code> or 01643 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 01644 * The HDF class of this type object <em>must</em> be H5T_INTEGER 01645 *\param id_list Pointer to memory in which to the read data. 01646 *\param status Passed back status of API call. 01647 */ 01648 void mhdf_readSetParentsChildren( hid_t data_handle, 01649 long offset, 01650 long count, 01651 hid_t hdf_integer_type, 01652 void* id_list, 01653 mhdf_Status* status ); 01654 void mhdf_readSetParentsChildrenWithOpt( hid_t data_handle, 01655 long offset, 01656 long count, 01657 hid_t hdf_integer_type, 01658 void* id_list, 01659 hid_t read_prop, 01660 mhdf_Status* status ); 01661 01662 /*@}*/ 01663 01664 /** 01665 *\defgroup mhdf_tag Tag data. 01666 * 01667 * The data for each tag can be stored in two places/formats: sparse and/or 01668 * dense. The data may be stored in both, but there should not be redundant 01669 * values for the same entity. 01670 * 01671 * Dense tag data is stored as multiple tables of tag values, one for each 01672 * element group. (Note: special \ref mhdf_ElemHandle values are available 01673 * for accessing dense tag data on nodes or meshsets via the \ref mhdf_node_type_handle 01674 * and \ref mhdf_set_type_handle functions.) Each dense tag table should contain 01675 * the same number of entries as the element connectivity table. The tag values 01676 * are associated with the corresponding element in the connectivity table. 01677 * 01678 * Sparse tag data is stored as a global table pair for each tag type. The first 01679 * if the pair of tables is a list of Global IDs. The second is the corresponding 01680 * tag value for each entity in the ID list. 01681 */ 01682 /*@{*/ 01683 01684 /** 01685 *\defgroup mhdf_tag_flag Tag type values (MOAB-specific) 01686 */ 01687 /*@{*/ 01688 01689 /** \brief Was dense tag data in mesh database */ 01690 #define mhdf_DENSE_TYPE 2 01691 /** \brief Was sparse tag data in mesh database */ 01692 #define mhdf_SPARSE_TYPE 1 01693 /** \brief Was bit-field tag data in mesh database */ 01694 #define mhdf_BIT_TYPE 0 01695 /** \brief Unused */ 01696 #define mhdf_MESH_TYPE 3 01697 01698 /*@}*/ 01699 01700 /** \brief Make type native-endian. 01701 * 01702 * Given an atomic HDF5 data type, return the built-in type 01703 * that matches the class of the passed type and is the specified 01704 * size. 01705 * 01706 * This function is provided to allow converting the stored tag 01707 * type in a file to the preferred type for it's representation 01708 * in memory when reading tag values. 01709 * 01710 * This function works only for atomic types. The returned type 01711 * will be a pre-defined HDF5 object and does not need to be 01712 * closed/released. 01713 * 01714 *\param input_type The type to convert. 01715 *\param size The desired size in bytes. 01716 *\param status Passed back status of API call. 01717 *\return The converted type. 01718 */ 01719 hid_t mhdf_getNativeType( hid_t input_type, int size, mhdf_Status* status ); 01720 01721 /** \brief Add a tag to the file 01722 * 01723 * Add a new tag to the file. This function must be called 01724 * to define the tag characteristics before values for the 01725 * tag can be written. 01726 * 01727 *\param file_handle The file 01728 *\param tag_name The tag name 01729 *\param tag_type The tag type. 01730 *\param size If tag_type == mhdf_BITFIELD, the number of 01731 * bits. If tag_type == mhdf_OPAQUE, the size 01732 * of the opaque type in bytes. Otherwise the 01733 * length of the array of tag_type entities associated 01734 * with each mesh entity, or 1 for a scalar value. 01735 *\param storage MOAB storage type (dense, sparse, etc.) 01736 *\param default_value Default value for tag, or NULL if none. 01737 *\param global_value Global value for tag, or NULL if none. 01738 *\param hdf_type If non-zero, assumed to be a user-specified type 01739 * for opaque data. Ignored if tag_type is not 01740 * mhdf_OPAQUE. 01741 *\param hdf_base_type Ignored if hdf_type is non-zero. If hdf_type is 01742 * zero and this type is non-zero, it is used either 01743 * as the type or as the base type for an array type for 01744 * default_value and global_value, respectively. Typically 01745 * used to specify the input data type for mhdf_ENTITY_ID 01746 * tags. 01747 */ 01748 void mhdf_createTag( mhdf_FileHandle file_handle, 01749 const char* tag_name, 01750 enum mhdf_TagDataType tag_type, 01751 int size, 01752 int storage, 01753 const void* default_value, 01754 const void* global_value, 01755 hid_t hdf_type, 01756 hid_t mhdf_base_type, 01757 mhdf_Status* status ); 01758 01759 /**\brief Get handle to HDF5 type object for tag data */ 01760 hid_t mhdf_getTagDataType( mhdf_FileHandle file_handle, const char* tag_name, mhdf_Status* status ); 01761 01762 /** \brief Add variable-length tag to file 01763 * 01764 * Add a new tag to the file. This function must be called 01765 * to define the tag characteristics before values for the 01766 * tag can be written. Use this function if the tag values 01767 * are not fixed-length. 01768 * 01769 *\param file_handle The file 01770 *\param tag_name The tag name 01771 *\param tag_type The tag type. 01772 *\param storage MOAB storage type (dense, sparse, etc.) 01773 *\param default_value Default value for tag, or NULL if none. 01774 *\param default_value_length Length of default value. 01775 *\param global_value Global value for tag, or NULL if none. 01776 *\param global_value_length Length of global value. 01777 *\param hdf_type If non-zero, assumed to be a user-specified type 01778 * for opaque data. Ignored if tag_type is not 01779 * mhdf_OPAQUE. 01780 *\param hdf_base_type Ignored if hdf_type is non-zero. If hdf_type is 01781 * zero and this type is non-zero, it is used either 01782 * as the type or as the base type for an array type for 01783 * default_value and global_value, respectively. Typically 01784 * used to specify the input data type for mhdf_ENTITY_ID 01785 * tags. 01786 */ 01787 void mhdf_createVarLenTag( mhdf_FileHandle file_handle, 01788 const char* tag_name, 01789 enum mhdf_TagDataType tag_type, 01790 int storage, 01791 const void* default_value, 01792 int default_value_length, 01793 const void* global_value, 01794 int global_value_length, 01795 hid_t hdf_type, 01796 hid_t hdf_base_type, 01797 mhdf_Status* status ); 01798 01799 /** \brief Get the number of tags in the file. 01800 * 01801 *\param file_handle The file. 01802 *\param status Passed back status of API call. 01803 *\return The number of tags. 01804 */ 01805 int mhdf_getNumberTags( mhdf_FileHandle file_handle, mhdf_Status* status ); 01806 01807 /** \brief Get the name for each tag defined in the file. 01808 * 01809 *\param file_handle The file. 01810 *\param num_names_out The length of the returned array of strings. 01811 *\param status Passed back status of API call. 01812 *\return An array of null-terminated strings. The array 01813 * and each string is allocated with <code>malloc</code>. 01814 * The caller should release this memory by calling 01815 * <code>free</code> for each string and the array. 01816 */ 01817 char** mhdf_getTagNames( mhdf_FileHandle file_handle, int* num_names_out, mhdf_Status* status ); 01818 01819 /** \brief Get the description of a specified tag. 01820 * 01821 * Get everything about a tag except the actual values. 01822 * 01823 *\param file_handle The file. 01824 *\param tag_name The name of the tag to retrieve the data for. 01825 *\param class_out The TSTT class of the tag data. 01826 *\param size_out Depends on value of class_out: 01827 * - mhdf_OPAQUE - size of opaque data in bytes 01828 * - mhdf_BITFIELD - number of bits 01829 * - if data is fixed-length array, length of array 01830 * - if data is single value, 1 01831 * - if data is a variable-length array, -1 01832 *\param tstt_storage_out The value of the TSTT enum for storage (dense, sparse, etc.) 01833 *\param have_default_out Non-zero if file contains a default value for the tag. 01834 * Length of default value if variable-lenth tag. 01835 *\param have_global_out Non-zero if the file contains a global/mesh value for the tag. 01836 *\param have_sparse_out Non-zero if the file contains a sparse data table for this tag. 01837 */ 01838 void mhdf_getTagInfo( mhdf_FileHandle file_handle, 01839 const char* tag_name, 01840 enum mhdf_TagDataType* class_out, 01841 int* size_out, 01842 int* tstt_storage_out, 01843 int* have_default_out, 01844 int* have_global_out, 01845 int* have_sparse_out, 01846 mhdf_Status* status ); 01847 01848 /** \brief Get the default and global values of the tag. 01849 * 01850 *\param file_handle The file. 01851 *\param tag_name The tag name. 01852 *\param output_data_type The HDF5 type for the memory into which the 01853 * tag data is to be written. If zero, then 01854 * the value(s) will be read as opaque data. 01855 *\param default_value Memory location at which to write the default 01856 * value of the tag. 01857 *\param global_value If the tag has a global value, the memory location 01858 * at which to write that value. 01859 *\param status Passed back status of API call. 01860 */ 01861 void mhdf_getTagValues( mhdf_FileHandle file_handle, 01862 const char* tag_name, 01863 hid_t output_data_type, 01864 void* default_value, 01865 void* global_value, 01866 mhdf_Status* status ); 01867 01868 /** \brief Check if the file contains dense tag data for the specified tag and element group. 01869 * 01870 * Check if there is dense tag data for a given element type for the specified 01871 * tag. 01872 * 01873 *\param file_handle The file. 01874 *\param tag_name The tag. 01875 *\param elem_group The element group handle, or the return value of 01876 * \ref mhdf_node_type_handle or \ref mhdf_set_type_handle 01877 * for nodes or sets respectively. 01878 *\param status Passed back status of API call. 01879 *\return Non-zero if file contains specified data. Zero otherwise. 01880 */ 01881 int mhdf_haveDenseTag( mhdf_FileHandle file_handle, const char* tag_name, const char* elem_group, mhdf_Status* status ); 01882 01883 /** \brief Create an object to hold dense tag values for a given element group. 01884 * 01885 *\param file_handle The file. 01886 *\param tag_name The tag. 01887 *\param elem_group The element group handle, or the return value of 01888 * \ref mhdf_node_type_handle or \ref mhdf_set_type_handle 01889 * for nodes or sets respectively. 01890 *\param num_values The number of tag values to be written. Must be 01891 * The same as the number of elements in the group. 01892 * Specified here to allow tag values to be written 01893 * before node coordinates, element connectivity or meshsets. 01894 *\param status Passed back status of API call. 01895 *\return Handle to data object in file. 01896 */ 01897 hid_t mhdf_createDenseTagData( mhdf_FileHandle file_handle, 01898 const char* tag_name, 01899 const char* elem_group, 01900 long num_values, 01901 mhdf_Status* status ); 01902 01903 /** \brief Open the object containing dense tag values for a given element group. 01904 * 01905 *\param file_handle The file. 01906 *\param tag_name The tag. 01907 *\param elem_group The element group handle, or the return value of 01908 * \ref mhdf_node_type_handle or \ref mhdf_set_type_handle 01909 * for nodes or sets respectively. 01910 *\param num_values_out The number of tag values to be written. Must be 01911 * The same as the number of elements in the group. 01912 *\param status Passed back status of API call. 01913 *\return Handle to data object in file. 01914 */ 01915 hid_t mhdf_openDenseTagData( mhdf_FileHandle file_handle, 01916 const char* tag_name, 01917 const char* elem_group, 01918 long* num_values_out, 01919 mhdf_Status* status ); 01920 01921 /** \brief Create file objects to store sparse tag data 01922 * 01923 * Create the file objects to store all sparse data for a given tag in. The 01924 * sparse data is stored in a pair of objects. The first is a vector of 01925 * global IDs. The second is a vector of tag values for each entity specified 01926 * in the list of global IDs. 01927 * 01928 *\param file_handle The file. 01929 *\param tag_name The tag. 01930 *\param num_values The number of tag values to be written. 01931 *\param entities_and_values_out The handles to the file objects. 01932 * The first is the vector of global IDs. The second 01933 * is the list of corresponding tag values. 01934 *\param status Passed back status of API call. 01935 */ 01936 void mhdf_createSparseTagData( mhdf_FileHandle file_handle, 01937 const char* tag_name, 01938 long num_values, 01939 hid_t entities_and_values_out[2], 01940 mhdf_Status* status ); 01941 01942 /** \brief Create file objects to store (sparse) variable-length tag data 01943 * 01944 * Create the file objects to store all sparse data for a given tag in. The 01945 * sparse data is stored in a pair of objects. The first is a vector of 01946 * global IDs. The second is a vector of tag values for each entity specified 01947 * in the list of global IDs. 01948 * 01949 *\param file_handle The file. 01950 *\param tag_name The tag. 01951 *\param num_entities The number of entities for which tag values are to be stored 01952 *\param num_values The total number of scalar values to be written (the 01953 * total number of bytes of data for all tags for opaque 01954 * data.) 01955 *\param entities_and_values_out The handles to the file objects. 01956 * The first is the vector of global IDs. The second 01957 * is the list of corresponding tag values. The third 01958 * is the handle to the index table. 01959 *\param status Passed back status of API call. 01960 */ 01961 void mhdf_createVarLenTagData( mhdf_FileHandle file_handle, 01962 const char* tag_name, 01963 long num_entities, 01964 long num_values, 01965 hid_t entities_and_values_out[3], 01966 mhdf_Status* status ); 01967 01968 /** \brief Create file objects to read sparse tag data 01969 * 01970 * Open the file objects containing all sparse data for a given tag in. The 01971 * sparse data is stored in a pair of objects. The first is a vector of 01972 * global IDs. The second is a vector of tag values for each entity specified 01973 * in the list of global IDs. For variable-length tags, a third table 01974 * containing end offsets for each tag value is returned in the third 01975 * position of the output hid_t array (see mhdf_readSparseTagIndices.) 01976 * 01977 *\param file_handle The file. 01978 *\param tag_name The tag. 01979 *\param num_entity_out The number of entities for which there are tag values. 01980 *\param num_values_out The number of data values. For fixed-length tags, 01981 * this is the same as num_entity_out. For 01982 * variable-length tags, it is the total number of 01983 * values in the data table. 01984 *\param entities_and_values_out The handles to the pair of file objects. 01985 * The first is the vector of global IDs. The second 01986 * is the list of corresponding tag values. The third 01987 * is the handle to the index table, iff the tag is 01988 * variable-length. If the tag is fixed-length, this 01989 * value is not set. 01990 *\param status Passed back status of API call. 01991 */ 01992 void mhdf_openSparseTagData( mhdf_FileHandle file_handle, 01993 const char* tag_name, 01994 long* num_entity_out, 01995 long* num_values_out, 01996 hid_t entities_and_values_out[3], 01997 mhdf_Status* status ); 01998 01999 /** \brief Write Global ID list for sparse tag data 02000 * 02001 *\param id_handle The first handle passed back from either 02002 * \ref mhdf_createSparseTagData or 02003 * \ref mhdf_openSparseTagData. 02004 *\param offset The offset at which to begin writing. 02005 *\param count The number of global IDs to write. 02006 *\param hdf_integer_type The type of the integer data in <code>id_list</code>. 02007 * Typically <code>H5T_NATIVE_INT</code> or 02008 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 02009 * The HDF class of this type object <em>must</em> be H5T_INTEGER 02010 *\param id_list The list of global IDs to write. 02011 *\param status Passed back status of API call. 02012 */ 02013 void mhdf_writeSparseTagEntities( hid_t id_handle, 02014 long offset, 02015 long count, 02016 hid_t hdf_integer_type, 02017 const void* id_list, 02018 mhdf_Status* status ); 02019 void mhdf_writeSparseTagEntitiesWithOpt( hid_t id_handle, 02020 long offset, 02021 long count, 02022 hid_t hdf_integer_type, 02023 const void* id_list, 02024 hid_t write_prop, 02025 mhdf_Status* status ); 02026 02027 /** \brief Write tag values 02028 * 02029 *\param value_handle The second handle passed back from either 02030 * \ref mhdf_createSparseTagData or 02031 * \ref mhdf_openSparseTagData; or the handle 02032 * returned by \ref mhdf_createDenseTagData or 02033 * \ref mhdf_openDenseTagData. 02034 *\param offset The offset at which to begin writing. 02035 *\param count The number of tag values to write. 02036 *\param hdf_tag_data_type The type of the data in memory. 02037 * It must be possible for the HDF library to convert 02038 * between this type and the type the tag data is stored 02039 * as. 02040 *\param tag_data The list of tag values to write. 02041 *\param status Passed back status of API call. 02042 */ 02043 void mhdf_writeTagValues( hid_t value_handle, 02044 long offset, 02045 long count, 02046 hid_t hdf_tag_data_type, 02047 const void* tag_data, 02048 mhdf_Status* status ); 02049 void mhdf_writeTagValuesWithOpt( hid_t value_handle, 02050 long offset, 02051 long count, 02052 hid_t hdf_tag_data_type, 02053 const void* tag_data, 02054 hid_t write_prop, 02055 mhdf_Status* status ); 02056 02057 /**\brief Write sparse tag end indices for variable-length tag data 02058 * 02059 * Write sparse tag end indices for variable-length tag data. 02060 * Each value in the list is the *last* index (zero-based) into the tag 02061 * data for the corresponding entity. 02062 * 02063 *\param tag_handle handle to the data object to write to. 02064 *\param offset The offset into the table at which to begin writting 02065 *\param count The number of values to write. 02066 *\param hdf_integer_type The type of the values pointed to by end_indices 02067 * (must be an integer type). 02068 *\param end_indices The values to store in the table. 02069 *\param status Output: API result. 02070 */ 02071 void mhdf_writeSparseTagIndices( hid_t tag_handle, 02072 long offset, 02073 long count, 02074 hid_t hdf_integer_type, 02075 const void* end_indices, 02076 mhdf_Status* status ); 02077 void mhdf_writeSparseTagIndicesWithOpt( hid_t tag_handle, 02078 long offset, 02079 long count, 02080 hid_t hdf_integer_type, 02081 const void* end_indices, 02082 hid_t write_prop, 02083 mhdf_Status* status ); 02084 02085 /** \brief Read Global ID list for sparse tag data 02086 * 02087 *\param id_handle The first handle passed back from either 02088 * \ref mhdf_createSparseTagData or 02089 * \ref mhdf_openSparseTagData. 02090 *\param offset The offset at which to begin reading. 02091 *\param count The number of global IDs to read. 02092 *\param hdf_integer_type The type of the integer data in <code>id_list</code>. 02093 * Typically <code>H5T_NATIVE_INT</code> or 02094 * <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>. 02095 * The HDF class of this type object <em>must</em> be H5T_INTEGER 02096 *\param id_list The memory location at which to store the global IDs. 02097 *\param status Passed back status of API call. 02098 */ 02099 void mhdf_readSparseTagEntities( hid_t id_handle, 02100 long offset, 02101 long count, 02102 hid_t hdf_integer_type, 02103 void* id_list, 02104 mhdf_Status* status ); 02105 void mhdf_readSparseTagEntitiesWithOpt( hid_t id_handle, 02106 long offset, 02107 long count, 02108 hid_t hdf_integer_type, 02109 void* id_list, 02110 hid_t read_prop, 02111 mhdf_Status* status ); 02112 02113 /** \brief Read tag values 02114 * 02115 *\param value_handle The second handle passed back from either 02116 * \ref mhdf_createSparseTagData or 02117 * \ref mhdf_openSparseTagData; or the handle 02118 * returned by \ref mhdf_createDenseTagData or 02119 * \ref mhdf_openDenseTagData. 02120 *\param offset The offset at which to begin reading. 02121 *\param count The number of tag values to read. 02122 *\param hdf_type The type of the data in memory. If this is specified, 02123 * it must be possible for the HDF library to convert 02124 * between this type and the type the tag data is stored 02125 * as. If zero, the values will be read as opaque data. 02126 *\param memory Memory location at which to store tag values. 02127 *\param status Passed back status of API call. 02128 */ 02129 void mhdf_readTagValues( hid_t value_handle, 02130 long offset, 02131 long count, 02132 hid_t hdf_type, 02133 void* memory, 02134 mhdf_Status* status ); 02135 void mhdf_readTagValuesWithOpt( hid_t value_handle, 02136 long offset, 02137 long count, 02138 hid_t hdf_type, 02139 void* memory, 02140 hid_t read_prop, 02141 mhdf_Status* status ); 02142 02143 /**\brief Read sparse tag end indices for variable-length tag data 02144 * 02145 * Read sparse tag end indices for variable-length tag data. 02146 * Each value in the list is the *last* index (zero-based) into the tag 02147 * data for the corresponding entity. 02148 * 02149 *\param tag_handle handle to the data object to read from. 02150 *\param offset The offset into the table at which to begin reading 02151 *\param count The number of values to read. 02152 *\param hdf_integer_type The type of the values pointed to by end_indices 02153 * (must be an integer type). 02154 *\param end_indices Memory in which to store the data read from the table. 02155 *\param status Output: API result. 02156 */ 02157 void mhdf_readSparseTagIndices( hid_t tag_handle, 02158 long offset, 02159 long count, 02160 hid_t hdf_integer_type, 02161 void* end_indices, 02162 mhdf_Status* status ); 02163 void mhdf_readSparseTagIndicesWithOpt( hid_t tag_handle, 02164 long offset, 02165 long count, 02166 hid_t hdf_integer_type, 02167 void* end_indices, 02168 hid_t read_prop, 02169 mhdf_Status* status ); 02170 02171 /*@}*/ 02172 02173 /*@}*/ 02174 02175 #ifdef __cplusplus 02176 } /* extern "C" */ 02177 #endif 02178 02179 #endif