====== zmap_GetDataPtr ======

===== Description =====

Retrieve the raw handle to map memory.

===== Files =====

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

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

<code="C">void* zmap_GetDataPtr(ZMAP hMap);</code>

===== 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:functions:zmap_tile_GetDataPtr]]'' instead).
  * The map is non-contiguous (test with ''[[zeolite:functions:zmap_IsContiguous]]'', and use ''[[zeolite:functions:zmap_GetScanlinePtr]]'' to retrieve memory address 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:

<code ="C++">
long offset = (x + nx * y) * PixelMemSize;
</code>

...where //ny// is the map width (in pixels) and //PixelMemSize// is the size in memory of one pixel (see ''[[zeolite:functions:zmap_GetPixelSize]]'').

To convert from memory offsets to pixel coordinates, use the following formulae:

<code="C++">
long x = (offset/PixelMemSize)%nx;
long y = (offset/PixelMemSize)/nx;
</code>

==== Use 'zmap_GetPixel' / 'zmap_SetPixel' where possible ====

It is recommended that, wherever possible, the ''[[zeolite:functions:zmap_GetPixel]]'' / ''[[zeolite:functions:zmap_SetPixel]]'' functions are used for accessing map data, instead of direct memory access with ''zmap_GetDataPtr''. Those functions include coordinate checking and memory protection, as well has handling mip-mapping and mosaic tile cache loading/saving and automatically.