====== zformat_Create======

===== Description =====

Create an instance of a file format handler for a particular project map. This function, or [[zeolite:functions:zformat_CreateGeneric]], must be called at least once by a file input/output plugin before it can be used to save or load map files.

===== Files =====

^ Declaration | ''Zeolite.h'' |
^ Implementation | ''Zeolite.cpp'' |

===== Function prototype =====

<code="C++">
ZFORMAT zformat_Create(const char* lpMapName, const char* lpLongName, const char* lpFileExt, const char* lpNativeProgramName);
</code>

===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //lpMapName//  |  ''const char*''  | A pointer to a C-style string, containing a valid map name (see comments). |
|  //lpLongName//  |  ''const char*''  | A pointer to a C-style string, containing the full display name of the format (e.g. "L3DT Design map File"). |
|  //lpFileExt//  |  ''const char*''  | A pointer to a C-style string, containing the file extension (e.g. "dmf"). |
|  //lpFileExt//  |  ''const char*''  | A pointer to a C-style string, containing the nameof the program to which this format is considered native (e.g. "L3DT"). |


===== Return value =====

Null if an error occurred or the format already existed, and otherwise a valid [[zeolite:types:ZFORMAT]] handle.

===== Comments =====

Valid project map names currently include:

  * "Design map"
  * "Heightfield"
  * "Water map"
  * "Salinity map"
  * "Attributes map"
  * "Terrain normals"
  * "Light map"
  * "Texture map"

More will be added in future.

===== Example =====

<code>
// create my format
ZFORMAT hFormat = zformat_Create("Design map", "L3DT Design Map File", "dmf", "L3DT");
if(!hFormat) {
  // do nothing; this probably means the format already exists.
} else {
  // set the flags
  zformat_SetFlags(hFormat, 
    ZFORMAT_FLAG_NATIVE|
    ZFORMAT_FLAG_MOSAIC|
    ZFORMAT_FLAG_LOAD|
    ZFORMAT_FLAG_SAVE|
    ZFORMAT_FLAG_LOADTILE|
    ZFORMAT_FLAG_SAVETILE); // native I/O and mosaic
}
</code>