====== map_GetDataPtr ======
===== Description =====
Retrieve the raw handle to map memory.
===== Function prototype =====
void* CExtAPI::map_GetDataPtr(ZMAP hMap);
===== Arguments =====
^ Name ^ Type ^ Comment ^
| hMap | ZMAP | The ZMAP handle of the map for which the data handle is to be retrieved. |
===== Return value =====
A null pointer if:
* The map is not allocated.
* The map is a mosaic (there is no contiguous memory in a mosaic; use [[zeolite:fuctions:tile_GetDataPtr]] instead).
* An unspecified error occurred.
A valid (non-null) pointer otherwise.
===== Comments =====
==== Pixel ordering ====
Pixels are ordered in rows going east-to-west, with rows ordered south to north. To convert from x/y coordinate to memory offset, use the following formula:
long offset = (x + nx * y) * PixelMemSize;
...where //ny// is the map width (in pixels) and //PixelMemSize// is the size in memory of one pixel (see [[zeolite:functions:map_GetPixelSize]]).
To convert from memory offsets to pixel coordinates, use the following formulae:
long x = (offset/PixelMemSize)%nx;
long y = (offset/PixelMemSize)/nx;
==== Use map_GetPixel/map_SetPixel where possible ====
It is recommended that, wherever possible, the [[zeolite:functions:map_GetPixel]]/[[zeolite:functions:map_SetPixel]] functions are used for accessing map data, instead of direct memory access with map_GetDataPtr. Those functions include coordinate checking and memory protection, as well has handling mip-mapping and mosaic tile cache loading/saving and automatically.