====== zmap_tile_GetDataPtr ======

===== Description =====

Retrieve the raw memory pointer to the data block of a mosaic tile. 

===== Files =====

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

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

<code="C++">
void* zmap_tile_GetDataPtr(void* hTile);
</code>

===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //hTile//  |  ''void*''  | A handle to a mosaic tile, as retrieved by the [[zeolite:functions:zmap_GetMosaicTile]] function. |

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

A null pointer if:
  * The tile handle is invalid.
  * The tile has not been locked for use via [[zeolite:functions:zmap_tile_SetLock]] (this is automatic when loading/saving tiles).
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>
long offset = (x + TileSize * y) * PixelMemSize;
</code>

...where //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>
long x = (offset/PixelMemSize)%TileSize;
long y = (offset/PixelMemSize)/TileSize;
</code>

==== Use zmap_tile_GetPixel / zmap_tile_SetPixel where possible ====

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