Converting a Pointer to an Array or List
========================================
Some functions in Global Mapper that give a collection of information may return a pointer to the start of an array
rather than the array itself. This is because the Python implementation of the Global Mapper SDK is derived from code
written originally in C++, in which pointers are generally returned instead of the entire data structure. The following
code is an example of a way to convert the pointer given by one of these function into an indexable array.

::

    import globalmapper as gm

    only_custom_shaders = False   # if true, the next line would only return the elevation shaders that you have created (i.e. not the default ones)
    pointer, size = gm.GetElevationShaders(only_custom_shaders)
    print("Size = ", size)
    # at this point, type(pointer) will return that pointer is a single GM_CustomShader_t object, due to the way Python handles pointers

    shader_array = gm.GM_CustomShader_array_frompointer(pointer)
    for in in range(size):
        print(shader_array[i])
    # 'pointer' is still a pointer, but now shader_array is a GM_CustomShader_array

    shader_list = gm.carray_to_list(shader_array, size)
    print("The shaders are now also stored in a ", type(shader_list))


In this case, the :doc:`GetElevationShaders function <../display/globalmapper.GetElevationShaders>` returns a pointer and
the size of the array. The array exists and is stored sequentially in memory as you would expect, but since you only
have the pointer, you can't use Python indexing to see an arbitrary entry. As far as Python is concerned, *pointer* is
just a single GM_CustomShader_t object. The solution is the **GM_CustomShader_array_frompointer** function, which returns
the information of the array starting at *pointer* to an indexable GM_CustomShader_array. There are several different
\*_array_frompointer functions for the types of arrays you might be given pointers to within Global Mapper (see below).
If you want to put the data into a standard Python list, use the function **carray_to_list(array, size)**.

For another case of converting a pointer to an array, see the example code for "Opening and Closing a Layer". That code
converts an array of layer handles using **GM_LayerHandle_array_frompointer**.

All functions for getting an array object from a pointer to an array in the GlobalMapper SDK:

-   **COLORREF_array_frompointer(COLORREF \*)**
-   **double_array_frompointer(double \*)**
-   **float_array_frompointer(float \*)**
-   **GM_AreaFeature_array_frompointer(GM_AreaFeature_t \*)**
-   **GM_AttrValue_array_frompointer(GM_AttrValue_t \*)**
-   **GM_CustomShader_array_frompointer(GM_CustomShader_t \*)**
-   **GM_ElevColor_array_frompointer(GM_ElevColor_t \*)**
-   **GM_FoundFeature_array_frompointer(GM_FoundFeature_t \*)**
-   **GM_GroundControlPoint_array_frompointer(GM_GroundControlPoint_t \*)**
-   **GM_LayerHandle_array_frompointer(GM_LayerHandle_t32 \*)**
-   **GM_LidarAttrInfo_array_frompointer(GM_LidarAttrInfo_t \*)**
-   **GM_LidarPoint_array_frompointer(GM_LidarPoint_t \*)**
-   **GM_LidarReturnInfo_array_frompointer(GM_LidarReturnInfo_t \*)**
-   **GM_OnlineSourceInfo_array_frompointer(GM_OnlineSourceInfo_t \*)**
-   **GM_PaletteEntry_array_frompointer(GM_PaletteEntry_t \*)**
-   **GM_Point_t_array_frompointer(GM_Point_t \*)**
-   **GM_ValName_array_frompointer(GM_ValName_t \*)**
-   **uint8_array_frompointer(uint8 \*)**
-   **uint32_array_frompointer(unsigned long \*)**