Main file reader API. More...

#include <molfile_plugin.h>

Public Attributes
vmdplugin_HEAD const char *	filename_extension
	Required header. More...

void (	open_file_read )(const char filepath, const char filetype, int *natoms)
	Try to open the file for reading. More...

int(*	read_structure )(void , int optflags, molfile_atom_t *atoms)
	Read molecular structure from the given file handle. More...

int(*	read_bonds )(void , int nbonds, int from, int to, float bondorder, int bondtype, int nbondtypes, char **bondtypename)
	Read bond information for the molecule. More...

int(*	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. More...

void(*	close_file_read )(void *)
	Close the file and release all data. More...

void (	open_file_write )(const char filepath, const char filetype, int natoms)
	Open a coordinate file for writing using the given header information. More...

int(*	write_structure )(void , int optflags, const molfile_atom_t atoms)
	Write structure information. More...

int(*	write_timestep )(void , const molfile_timestep_t )
	Write a timestep to the coordinate file. More...

void(*	close_file_write )(void *)
	Close the file and release all data. More...

int(*	read_volumetric_metadata )(void , int nsets, molfile_volumetric_t **metadata)
	Retrieve metadata pertaining to volumetric datasets in this file. More...

int(*	read_volumetric_data )(void , int set, float datablock, float *colorblock)
	Read the specified volumetric data set into the space pointed to by datablock. More...

int(*	read_rawgraphics )(void , int nelem, const molfile_graphics_t **data)
	Read raw graphics data stored in this file. More...

int(*	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. More...

int(*	write_bonds )(void , int nbonds, int from, int to, float bondorder, int bondtype, int nbondtypes, char *bondtypename)
	Write bond information for the molecule. More...

int(*	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. More...

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)
	Read in Angles, Dihedrals, Impropers, and Cross Terms and optionally types. More...

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)
	Write out Angles, Dihedrals, Impropers, and Cross Terms (Cross terms pertain to the CHARMM/NAMD CMAP feature) More...

int(*	read_qm_metadata )(void , molfile_qm_metadata_t metadata)
	Retrieve metadata pertaining to timestep independent QM datasets in this file. More...

int(*	read_qm_rundata )(void , molfile_qm_t qmdata)
	Read timestep independent QM data. More...

int(*	read_timestep )(void , int natoms, molfile_timestep_t , molfile_qm_metadata_t , molfile_qm_timestep_t )
	Read the next timestep from the file. More...

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 *)
	Console output, READ-ONLY function pointer. More...

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.

Member Data Documentation

void(* PLMD::molfile::molfile_plugin_t::close_file_read)(void *)

Close the file and release all data.

The handle cannot be reused.

void(* PLMD::molfile::molfile_plugin_t::close_file_write)(void *)

Close the file and release all data.

The handle cannot be reused.

int(* PLMD::molfile::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* PLMD::molfile::molfile_plugin_t::filename_extension

Required header.

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".

void*(* PLMD::molfile::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.

void*(* PLMD::molfile::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.

int(* PLMD::molfile::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)

int(* PLMD::molfile::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.

int(* PLMD::molfile::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.

int(* PLMD::molfile::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.

int(* PLMD::molfile::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().

int(* PLMD::molfile::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().

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

int(* PLMD::molfile::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.

int(* PLMD::molfile::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.

int(* PLMD::molfile::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.

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

int(* PLMD::molfile::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.

int(* PLMD::molfile::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.

int(* PLMD::molfile::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)

int(* PLMD::molfile::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.

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

Write structure information.

Return success.

int(* PLMD::molfile::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.

int(* PLMD::molfile::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.

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

molfile/molfile_plugin.h

Public Attributes

Detailed Description

Member Data Documentation