====== zmap_GetMipmapLevel ======

===== Description =====

Get a mipmap (as a ZMAP handle) for a given map.

===== Files =====

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

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

<code="C++">
ZMAP zmap_GetMipmapLevel(ZMAP hMap, long MipLevel);
</code>

===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //hMap//  |  ''ZMAP''  | A handle to a map variable, a mipmap of which is to be retrieved. |
|  //MipLevel//  |  ''long''  | The sub-sampling factor of the desired mipmap. See comments below. |

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

A null pointer if the desired mipmap does not exist, or if an error occurred. Otherwise, a non-null handle to a map variable is returned. 

===== Comments =====


==== MipLevel =====

//MipLevel// is the ratio of the side-lengths of the full-resolution map (referenced by //hMap//) to the side-lengths of the desired mipmap. So, for example, if you want to retrieve the mipmap that is one-quarter of the resolution of the full-res map, enter a //MipLevel// if 4. 

Note, however, that not all values of //MipLevel// are allowed. Allowed values are given by:

<code>
MipLevel = ResStep ^ n
</code>

Where:
  * //ResStep// is the resolution step (factor) between successive mipmap levels (see [[zeolite:functions:zmap_GetMipmapResStep]])
  * //n// is a positive integer.
  * //MipLevel// is smaller than or equal to //MaxLevel//, where //MaxLevel// is the maximum mipmap level (see [[zeolite:functions:zmap_GetMipmapMaxLevel]]).