====== hfzSave ======

===== Description =====

Save a floating-point map as a HF2/HFZ file.

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

<code>long hfzSave(const char* lpFileName, long Format, hfzHeader& fh, float* pData, LIBHFZ_PROG_CALLBACK lpProgCallback, void* lpCallbackParam);</code>

===== Arguments =====

^ Name ^ Type ^ Comment ^
| lpFileName | const char* | The file name of the file to be saved. |
| Format | long | The type of file to be opened. May be either LIBHFZ_FORMAT_HF2 (uncompressed) or LIBHFZ_FORMAT_HF2_GZ (compressed). |
| fh | hfzHeader& | The hfzHeader struct to be written to the file, as initialised by [[libhfz:functions:hfzHeader_Init]]. |
| pData | float* | A handle to the map data. Please refer to the [[:l3dt:formats:specs:hf2#map_data|HF2 file specification]] for the required pixel order. |
| lpProgCallback | LIBHFZ_PROG_CALLBACK | A handle to a callback function for displaying progress (see comments below). May be NULL if no callback is desired. |
| lpCallbackParam | void* | A handle to a user-defined parameter to be passed back to the //lpProgCallback// function, if used. |


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

LIBHFZ_STATUS_OK if the file was saved successfully, and otherwise an error code. Use [[libhfz:functions:hfzGetErrorStr]] to retrieve the error description. 

===== Comments =====


==== Using lpProgCallback ====

The prototype of the callback function must be:

<code>
long __stdcall MyCallbackFuncName(float Progress);
</code>

The value of //Progress// passed by LibHFZ varies from 0 to 1. 

The value returned by the callback must be:
  * LIBHFZ_STATUS_OK (0) if the file saving/loading is to proceed.
  * A non-zero value if the file saving/loading should be cancelled, such as LIBHFZ_USER_ABORT (-15).