---

molfile_plugin_t Struct Reference

#include <molfile_plugin.h>

List of all members.

Public Attributes
vmdplugin_HEAD const char *	filename_extension
void *(*	open_file_read )(const char *filepath, const char *filetype, int *natoms)
int(*	read_structure )(void *, int *optflags, molfile_atom_t *atoms)
int(*	read_bonds )(void *, int *nbonds, int **from, int **to, float **bondorder, int **bondtype, int *nbondtypes, char ***bondtypename)
int(*	read_next_timestep )(void *, int natoms, molfile_timestep_t *)
void(*	close_file_read )(void *)
void *(*	open_file_write )(const char *filepath, const char *filetype, int natoms)
int(*	write_structure )(void *, int optflags, const molfile_atom_t *atoms)
int(*	write_timestep )(void *, const molfile_timestep_t *)
void(*	close_file_write )(void *)
int(*	read_volumetric_metadata )(void *, int *nsets, molfile_volumetric_t **metadata)
int(*	read_volumetric_data )(void *, int set, float *datablock, float *colorblock)
int(*	read_volumetric_data_ex )(void *, molfile_volumetric_readwrite_t *v)
int(*	read_rawgraphics )(void *, int *nelem, const molfile_graphics_t **data)
int(*	read_molecule_metadata )(void *, molfile_metadata_t **metadata)
int(*	write_bonds )(void *, int nbonds, int *from, int *to, float *bondorder, int *bondtype, int nbondtypes, char **bondtypename)
int(*	write_volumetric_data )(void *, molfile_volumetric_t *metadata, float *datablock, float *colorblock)
int(*	write_volumetric_data_ex )(void *, molfile_volumetric_t *metadata, molfile_volumetric_readwrite_t *v)
int(*	read_angles )(void *handle, int *numangles, int **angles, int **angletypes, int *numangletypes, char ***angletypenames, int *numdihedrals, int **dihedrals, int **dihedraltypes, int *numdihedraltypes, char ***dihedraltypenames, int *numimpropers, int **impropers, int **impropertypes, int *numimpropertypes, char ***impropertypenames, int *numcterms, int **cterms, int *ctermcols, int *ctermrows)
int(*	write_angles )(void *handle, int numangles, const int *angles, const int *angletypes, int numangletypes, const char **angletypenames, int numdihedrals, const int *dihedrals, const int *dihedraltypes, int numdihedraltypes, const char **dihedraltypenames, int numimpropers, const int *impropers, const int *impropertypes, int numimpropertypes, const char **impropertypenames, int numcterms, const int *cterms, int ctermcols, int ctermrows)
int(*	read_qm_metadata )(void *, molfile_qm_metadata_t *metadata)
int(*	read_qm_rundata )(void *, molfile_qm_t *qmdata)
int(*	read_timestep_pagealign_size )(void *, int *pagealignsize)
int(*	read_timestep )(void *, int natoms, molfile_timestep_t *, molfile_qm_metadata_t *, molfile_qm_timestep_t *)
int(*	read_timestep_metadata )(void *, molfile_timestep_metadata_t *)
int(*	read_qm_timestep_metadata )(void *, molfile_qm_timestep_metadata_t *)
int(*	cons_fputs )(const int, const char *)

---

Detailed Description

Main file reader API. Any function in this struct may be NULL if not implemented by the plugin; the application checks this to determine what functionality is present in the plugin.

Definition at line 640 of file molfile_plugin.h.

---

Member Data Documentation

void(* molfile_plugin_t::close_file_read)(void *)

Close the file and release all data. The handle cannot be reused. Referenced by main, and VMDPLUGIN_init.

void(* molfile_plugin_t::close_file_write)(void *)

Close the file and release all data. The handle cannot be reused. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::cons_fputs)(const int, const char*)

Console output, READ-ONLY function pointer. Function pointer that plugins can use for printing to the host application's text console. This provides a clean way for plugins to send message strings back to the calling application, giving the caller the ability to prioritize, buffer, and redirect console messages to an appropriate output channel, window, etc. This enables the use of graphical consoles like TkCon without losing console output from plugins. If the function pointer is NULL, no console output service is provided by the calling application, and the output should default to stdout stream. If the function pointer is non-NULL, all output will be subsequently dealt with by the calling application. XXX this should really be put into a separate block of application-provided read-only function pointers for any application-provided services

vmdplugin_HEAD const char* molfile_plugin_t::filename_extension

Filename extension for this file type. May be NULL if no filename extension exists and/or is known. For file types that match several common extensions, list them in a comma separated list such as: "pdb,ent,foo,bar,baz,ban" The comma separated list will be expanded when filename extension matching is performed. If multiple plugins solicit the same filename extensions, the one that lists the extension earliest in its list is selected. In the case of a "tie", the first one tried/checked "wins". Definition at line 656 of file molfile_plugin.h. Referenced by VMDPLUGIN_init.

void*(* molfile_plugin_t::open_file_read)(const char *filepath, const char *filetype, int *natoms)

Try to open the file for reading. Return an opaque handle, or NULL on failure. Set the number of atoms; if the number of atoms cannot be determined, set natoms to MOLFILE_NUMATOMS_UNKNOWN. Filetype should be the name under which this plugin was registered; this is provided so that plugins can provide the same function pointer to handle multiple file types. Referenced by main, and VMDPLUGIN_init.

void*(* molfile_plugin_t::open_file_write)(const char *filepath, const char *filetype, int natoms)

Open a coordinate file for writing using the given header information. Return an opaque handle, or NULL on failure. The application must specify the number of atoms to be written. filetype should be the name under which this plugin was registered. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_angles)(void *handle, int *numangles, int **angles, int **angletypes, int *numangletypes, char ***angletypenames, int *numdihedrals, int **dihedrals, int **dihedraltypes, int *numdihedraltypes, char ***dihedraltypenames, int *numimpropers, int **impropers, int **impropertypes, int *numimpropertypes, char ***impropertypenames, int *numcterms, int **cterms, int *ctermcols, int *ctermrows)

Read in Angles, Dihedrals, Impropers, and Cross Terms and optionally types. (Cross terms pertain to the CHARMM/NAMD CMAP feature) Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_bonds)(void *, int *nbonds, int **from, int **to, float **bondorder, int **bondtype, int *nbondtypes, char ***bondtypename)

Read bond information for the molecule. On success the arrays from and to should point to the (one-based) indices of bonded atoms. Each unique bond should be specified only once, so file formats that list bonds twice will need post-processing before the results are returned to the caller. If the plugin provides bond information, but the file loaded doesn't actually contain any bond info, the nbonds parameter should be set to 0 and from/to should be set to NULL to indicate that no bond information was actually present, and automatic bond search should be performed. If the plugin provides bond order information, the bondorder array will contain the bond order for each from/to pair. If not, the bondorder pointer should be set to NULL, in which case the caller will provide a default bond order value of 1.0. If the plugin provides bond type information, the bondtype array will contain the bond type index for each from/to pair. These numbers are consecutive integers starting from 0. the bondtypenames list, contains the corresponding names, if available, as a NULL string terminated list. nbondtypes is provided for convenience and consistency checking. These arrays must be freed by the plugin in the close_file_read function. This function can be called only after read_structure. Return MOLFILE_SUCCESS if no errors occur. Referenced by main, and VMDPLUGIN_init.

int(* molfile_plugin_t::read_molecule_metadata)(void *, molfile_metadata_t **metadata)

Read molecule metadata such as what database (if any) this file/data came from, what the accession code for the database is, textual remarks and other notes pertaining to the contained structure/trajectory/volume and anything else that's informative at the whole file level. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_next_timestep)(void *, int natoms, molfile_timestep_t *)

XXX this function will be augmented and possibly superceded by a new QM-capable version named read_timestep, when finished. Read the next timestep from the file. Return MOLFILE_SUCCESS, or MOLFILE_EOF on EOF. If the molfile_timestep_t argument is NULL, then the frame should be skipped. Otherwise, the application must prepare molfile_timestep_t by allocating space in coords for the corresponding number of coordinates. The natoms parameter exists because some coordinate file formats (like CRD) cannot determine for themselves how many atoms are in a timestep; the app must therefore obtain this information elsewhere and provide it to the plugin. Referenced by main, and VMDPLUGIN_init.

int(* molfile_plugin_t::read_qm_metadata)(void *, molfile_qm_metadata_t *metadata)

Retrieve metadata pertaining to timestep independent QM datasets in this file. The metadata are the sizes of the QM related data structure arrays that will be populated by the plugin when read_qm_rundata is called. Since the allocation of these arrays is done by VMD rather than the plugin, VMD needs to know the sizes beforehand. Consequently read_qm_metadata has to be called before read_qm_rundata. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_qm_rundata)(void *, molfile_qm_t *qmdata)

Read timestep independent QM data. Typical data that are defined only once per trajectory are general info about the calculation (such as the used method), the basis set and normal modes. The data structures to be populated must have been allocated before by VMD according to sizes obtained through read_qm_metadata. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_qm_timestep_metadata)(void *, molfile_qm_timestep_metadata_t *)

Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_rawgraphics)(void *, int *nelem, const molfile_graphics_t **data)

Read raw graphics data stored in this file. Return the number of data elements and the data itself as an array of molfile_graphics_t in the pointer provided by the application. The plugin is responsible for freeing the data when the file is closed. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_structure)(void *, int *optflags, molfile_atom_t *atoms)

Read molecular structure from the given file handle. atoms is allocated by the caller and points to space for natoms. On success, place atom information in the passed-in pointer. optflags specifies which optional fields in the atoms will be set by the plugin. Referenced by main, and VMDPLUGIN_init.

int(* molfile_plugin_t::read_timestep)(void *, int natoms, molfile_timestep_t *, molfile_qm_metadata_t *, molfile_qm_timestep_t *)

Read the next timestep from the file. Return MOLFILE_SUCCESS, or MOLFILE_EOF on EOF. If the molfile_timestep_t or molfile_qm_metadata_t arguments are NULL, then the coordinate or qm data should be skipped. Otherwise, the application must prepare molfile_timestep_t and molfile_qm_timestep_t by allocating space for the corresponding number of coordinates, orbital wavefunction coefficients, etc. Since it is common for users to want to load only the final timestep data from a QM run, the application may provide any combination of valid, or NULL pointers for the molfile_timestep_t and molfile_qm_timestep_t parameters, depending on what information the user is interested in. The natoms and qm metadata parameters exist because some file formats cannot determine for themselves how many atoms etc are in a timestep; the app must therefore obtain this information elsewhere and provide it to the plugin. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_timestep_metadata)(void *, molfile_timestep_metadata_t *)

Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_timestep_pagealign_size)(void *, int *pagealignsize)

Query the molfile plugin to determine whether or not memory allocations used for atomic coordinates and PBC unit cell information need to be aligned to a particular virtual memory or filesystem page size boundary to facilitate kernel-bypass unbuffered I/O, e.g., as used by jsplugin. This API should be called prior to the first call to read a timestep. The required page alignment size (in bytes) is returned to the caller. If this API has not been called, then the molfile plugin should revert to standard kernel-buffered I/O and suffer the associated performance loss. The caller can be assured that the plugin will not request any page alignment size that is greater than the value of MOLFILE_DIRECTIO_MAX_BLOCK_SIZE, both as a runtime sanity check, and to ensure that a caller that is unable to perform the max aligned allocation doesn't call the API in the first place. If a page-aligned allocation is not required for the file being read, the plugin will return an alignment size of 1. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_volumetric_data)(void *, int set, float *datablock, float *colorblock)

Read the specified volumetric data set into the space pointed to by datablock. The set is specified with a zero-based index. The space allocated for the datablock must be equal to xsize * ysize * zsize. No space will be allocated for colorblock unless has_color is nonzero; in that case, colorblock should be filled in with three RGB floats per datapoint. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_volumetric_data_ex)(void *, molfile_volumetric_readwrite_t *v)

Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::read_volumetric_metadata)(void *, int *nsets, molfile_volumetric_t **metadata)

Retrieve metadata pertaining to volumetric datasets in this file. Set nsets to the number of volumetric data sets, and set *metadata to point to an array of molfile_volumetric_t. The array is owned by the plugin and should be freed by close_file_read. The application may call this function any number of times. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::write_angles)(void *handle, int numangles, const int *angles, const int *angletypes, int numangletypes, const char **angletypenames, int numdihedrals, const int *dihedrals, const int *dihedraltypes, int numdihedraltypes, const char **dihedraltypenames, int numimpropers, const int *impropers, const int *impropertypes, int numimpropertypes, const char **impropertypenames, int numcterms, const int *cterms, int ctermcols, int ctermrows)

Write out Angles, Dihedrals, Impropers, and Cross Terms (Cross terms pertain to the CHARMM/NAMD CMAP feature) Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::write_bonds)(void *, int nbonds, int *from, int *to, float *bondorder, int *bondtype, int nbondtypes, char **bondtypename)

Write bond information for the molecule. The arrays from and to point to the (one-based) indices of bonded atoms. Each unique bond will be specified only once by the caller. File formats that list bonds twice will need to emit both the from/to and to/from versions of each. This function must be called before write_structure. Like the read_bonds routine, the bondorder pointer is set to NULL if the caller doesn't have such information, in which case the plugin should assume a bond order of 1.0 if the file format requires bond order information. Support for bond types follows the bondorder rules. bondtype is an integer array of the size nbonds that contains the bond type index (consecutive integers starting from 0) and bondtypenames contain the corresponding strings, in case the naming/numbering scheme is different from the index numbers. if the pointers are set to NULL, then this information is not available. bondtypenames can only be used of bondtypes is also given. Return MOLFILE_SUCCESS if no errors occur. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::write_structure)(void *, int optflags, const molfile_atom_t *atoms)

Write structure information. Return success. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::write_timestep)(void *, const molfile_timestep_t *)

Write a timestep to the coordinate file. Return MOLFILE_SUCCESS if no errors occur. If the file contains structure information in each timestep (like a multi-entry PDB), it will have to cache the information from the initial calls from write_structure. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::write_volumetric_data)(void *, molfile_volumetric_t *metadata, float *datablock, float *colorblock)

Write the specified volumetric data set into the space pointed to by datablock. The * allocated for the datablock must be equal to xsize * ysize * zsize. No space will be allocated for colorblock unless has_color is nonzero; in that case, colorblock should be filled in with three RGB floats per datapoint. Referenced by VMDPLUGIN_init.

int(* molfile_plugin_t::write_volumetric_data_ex)(void *, molfile_volumetric_t *metadata, molfile_volumetric_readwrite_t *v)

---

The documentation for this struct was generated from the following file:

• molfile_plugin.h

---