CreateRoute

This method allows the client to create a route object. A route is an array of waypoints. Each waypoint defines the position of the camera and its speed at that waypoint.

HRESULT CreateRoute (

[in, defaultvalue(0)] VARIANT SafeArrayWaypointStruct,

[in, defaultvalue(0)] HeightStyleCode HeightStyle,

 [in, defaultvalue(0)] long GroupID,

[in, defaultvalue("")] BSTR Description,

[out, retval] ITerrainRoute5** pITerrainRoute5)

Parameters:

• SafeArrayWaypointStruct – An array of waypoint structures that define the route. If the client passes NULL in this parameter, the route object is initially created without any waypoints (and therefore can not be played). The user can use the ITerrainRoute5::AddWaypoint() method to add waypoints to the route. The route must have at least two waypoints in order to be able to play.
  See: ITerrainRoute5::GetWaypoint() for more information about the SafeArrayWaypointStruct parameter.

• HeightStyle – An enum determining how the route waypoints elevation is interpreted.

The HeightStyleCode enum can use any of the following values:

• HSC_TERRAIN_RELATIVE = 0
  The height above the terrain of the route’s waypoints, is determined by the Elevation points in the SafeArrayWaypointStruct parameter.

• HSC_TERRAIN_ABSOLUTE = 3
  The height relative to the terrain database vertical datum base ellipsoid of the route’s waypoints, is determined by the Elevation points in the SafeArrayWaypointStruct parameter.

• GroupID – The Information Tree group in which the route is created. If it is set to zero, the object is created in the route. You can obtain the GroupID by one of the following methods:

• Create the group using the IInformationTree5::CreateGroup method.

• Find the group if you know the name of the group using IInformationTree5::FindItem.

• Traverse the Tree using IInformationTree5 methods such as GetNextItem, until you come to the desired GroupID.

• Description – The name of the route as it appears in the Information Window. If an empty string is passed into this parameter, TerraExplorer assigns it a unique name.

• pITerrainRoute5 – An interface pointer to the newly created route. This parameter must not be Null.

Return Values:

The return value obtained from the returned HRESULT can be one of the following: