QueryElevationBufferAsync

This method returns an array of elevation values for a designated area of the terrain. The query includes all ground objects, modify terrain objects, 3DML, etc. that are currently loaded on the terrain. If a layer is being streamed, this QueryElevationBuffer only returns elevation values for features that were already streamed at the time this method is called.

The designated area’s coordinates and coordinate system units should be passed in the coordinate system of the terrain and they are not translated by ICoordServices.SourceCoordinateSystem like other places in the API. See ITerrain80.CoordinateSystem for information.

QueryElevationBufferAsync executes asynchronously, immediately returning an ITerraExplorerAsync80, thereby ensuring that control is promptly handed back to the calling function. The ITerraExplorerAsync80 object provides a callback-based mechanism similar to the JavaScript promise and the C# Task that offers the following functionality:

§   Allows for handling the various stages of the asynchronous operation, from tracking progress to managing rejection/error, and finally resolving the operation (using OnProgress, OnReject, and OnResolve respectively).

§   Upon resolution of the query, enables the passing of a SafeArray of float values representing the elevation values in the designated area, to the OnResolve callback.

If you want to execute synchronously, use QueryElevationBuffer instead.

Note:    Make sure the terrain opacity is set to 100% (ITerrain.Opacity = 1) before calling this method.

Parameters

UpperLeftX

The West-East coordinate of the elevation layer’s upper left corner in the terrain coordinate system.

UpperLeftY

The North-South coordinate of the elevation layer’s upper left corner in the terrain coordinate system.

ResX

The X cell resolution in the terrain coordinate system units.

ResY

The Y cell resolution in the terrain coordinate system units.

DimensionX

The width, in pixels, of the raster array. This value can range from 512-2048.

DimensionY

The height, in pixels, of the raster array. This value can range from 512-2048.

Return Value

pVal

An ITerraExplorerAsync80 object, which provides a callback-based mechanism similar to the JavaScript promise and the C# Task that offers the following functionality:

·          Allows for handling the various stages of the asynchronous operation, from tracking progress to managing rejection/error, and finally resolving the operation (using OnProgress, OnReject, and OnResolve respectively).

·          Upon resolution of the query, enables the passing of a SafeArray of float values representing the elevation values in the designated area, to the OnResolve callback.

Exceptions

See: HRESULT Return Values for a list of possible values returned by the HRESULT.