====== hfzLoad ======

===== Description =====

Load a HF2/HFZ file from disk into memory. Unlike [[libhfz:functions:hfzLoadEx]], this function does not automatically allocate the memory block.

===== Function prototype =====
<code>
long hfzLoad(const char* lpFileName, hfzHeader& fh, float * pData, LIBHFZ_PROG_CALLBACK lpProgCallback, void* lpCallbackParam);
</code>

===== Arguments =====
^ Name ^ Type ^ Description ^
| lpFileName | const char* | The file name of the file to be loaded. |
| fh | hfzHeader& | The hfzHeader struct to be read from the file. |
| pData | float* | A handle to the memory block to receive the map data. Please see comments for requirements. |
| 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 loaded successfully, and otherwise an error code. Use [[libhfz:functions:hfzGetErrorStr]] to retrieve the error description. 

===== Comments =====

==== Initialising memory ====

This function requires that the //pData// memory block be allocated prior to the call. The required size is:
<code>
4 * nx * ny
</code>
...where //nx// and //ny// are the map widths and heights in pixels. These values can be read from the file using [[libhfz:functions:hfzReadHeader2]]. Alternatively, you may use [[libhfz:functions:hfzLoadEx]], which initialises the memory automatically. 

==== Using lpProgCallback ====

Please consult the comments for [[libhfz:functions:hfzsave#Using lpProgCallback|hfzSave]]