SetPosition

The SetPosition() method sets the position and orientation of the object on the terrain. If the client handles the _ITerraExplorerEvents4::OnFrame() event, it can set the object position in every frame (according to a GPS input, for example) to create a flowing motion of the object, on the terrain.

HRESULT SetPosition(

[in] double X,

[in] double Y,

[in] double Elevation,

[in] double Yaw,

[in] double Pitch,

[in] double Roll,

[in, defaultvalue(0)] long Flags)

Parameters:

• X – The West-East coordinate of the waypoint in MPT units. You can use the ITerrain interface to retrieve information about the MPT units. If you are working in Lat-Long format, the Lat-Long values are in decimal Lat-Long.

• Y – The North-South coordinate of the waypoint in MPT units. You can use the ITerrain interface to retrieve information about the MPT units. If you are working in Lat-Long format, the Lat-Long values are in decimal Lat-Long.

• Elevation – The altitude of the location in the default altitude type of the object, unless otherwise defined in the Flags parameter. You can get the default altitude type by using the ITerrainLocation5::GetPositionEx() method.

• Yaw – If the object is a pure location object, this is the angle between the viewer direction and the location point of interest (determined by the X, Y and Elevation parameters). For all other objects, this is the yaw orientation of the object. See: “Yaw, Pitch and Roll Angles”.

• Pitch – If the object is a pure location object, this is the angle between the viewer camera tilt and the point of interest (determined by the X, Y and Elevation parameters). For all other objects, this is the pitch orientation of the object. See:  “Yaw, Pitch and Roll Angles”.

• Roll – If the object is a pure location object, this parameter is ignored. For all other objects, this is the roll orientation of the object. See: “Yaw, Pitch and Roll Angles”.

• Flags – Determine how the first six parameters are interpreted. For example, the client can set a new position for the object, relative to its current position. Below are the valid flags (from which you can form different combinations) for this method.

• IGNORE_X = 1
  When set, the X parameter is ignored (retaining the current X-coordinate of the object).

• IGNORE_HEIGHT  = 2
  When set, the Elevation parameter is ignored (retaining the current elevation of the object).

• IGNORE_Y= 4
  When set, the Y parameter is ignored (retaining the current Y-coordinate of the object).

• IGNORE_POSITION = 7
  When set, the X, Y and Elevation parameters are ignored (retaining the current position of the object).

• IGNORE_YAW = 8
  When set, the Yaw parameter is ignored (retaining the current yaw of the object).

• IGNORE_PITCH  = 16
  When set, the Pitch parameter is ignored (retaining the current pitch of the object).

• IGNORE_ROLL  = 32
  When set, the Roll parameter is ignored (retaining the current roll of the object)

• IGNORE_ORIENTATION = 56
  When set, the Yaw, Pitch and Roll parameters are ignored (retaining the current orientation of the object)

• NEW_ELEVATION_RELATIVE_TO_CURRENT_ELEVATION = 64
  When set, the value of the Elevation parameter is added to the current elevation of the object.

•  NEW_POS_RELATIVE_TO_CURRENT_POS = 128
  When set, the values of the X and Y coordinates are added to the current X and Y coordinates of the object.

• NEW_ANGLES_RELATIVE_TO_CURRENT_ANGLES = 256
  When set, the values of the Yaw, Pitch and Roll parameters are added to the current yaw, pitch and roll of the object.

• HEIGHT_AGL = 4096
  When set, the value of the Elevation parameter is interpreted as altitude above the ground, in meters. Do not use this flag with the NEW_ELEVATION_RELATIVE_TO_CURRENT_ELEVATION flag.

• HEIGHT_ABSOLUTE = 8192
  When set, the value of the Elevation parameter is interpreted as relative to the terrain database vertical datum base ellipsoid, in meters. Do not use this flag with the NEW_ELEVATION_RELATIVE_TO_CURRENT_ELEVATION flag.

Return Values:

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