World Wind v1.4 API Specification

From World Wind Wiki

Jump to: navigation, search

Key Interfaces that will be defined in the Plugin API

namespace WorldWindSDK
{
	/// <summary>
	/// Interface for which all Non-GUI Renderable elements must derive.
	/// </summary>
	public interface IRenderable
	{
		#region Methods
		/// <summary>
		/// Disposes this instance.
		/// </summary>
		void Dispose();
		
		/// <summary>
		/// Initializes this instance.
		/// </summary>
		void Initialize();
		
		/// <summary>
		/// Renders the IRenderable with the specified camera.
		/// </summary>
		/// <param name="camera">Camera.</param>
		void Render(ICamera camera);
		#endregion

		#region Properties
		/// <summary>
		/// Gets or sets the child renderables.
		/// </summary>
		/// <value></value>
		IRenderableCollection ChildRenderables{get;set;}
		
		/// <summary>
		/// Gets a value indicating whether this <see cref="[interface]"/> is disposed.
		/// </summary>
		/// <value>
		/// 	<c>true</c> if disposed; otherwise, <c>false</c>.
		/// </value>
		bool Disposed{get;}
		
		/// <summary>
		/// Gets a value indicating whether this <see cref="[interface]"/> is initialized.
		/// </summary>
		/// <value>
		/// 	<c>true</c> if initialized; otherwise, <c>false</c>.
		/// </value>
		bool Initialized{get;}
		
		/// <summary>
		/// Gets or sets the meta data.
		/// </summary>
		/// <value></value>
		Hashtable MetaData{get;set;}
		
		/// <summary>
		/// Gets or sets the Id.
		/// </summary>
		/// <value></value>
		string Id{get;set;}
		
		/// <summary>
		/// Gets or sets the opacity. 0 = Transparent, 255 = Fully Opaque
		/// </summary>
		/// <value></value>
		byte Opacity{get;set;}
		
		/// <summary>
		/// Gets or sets the orientation.
		/// </summary>
		/// <value></value>
		Quaternion Orientation{get;set;}
		
		/// <summary>
		/// Gets or sets the parent renderable.
		/// </summary>
		/// <value></value>
		IRenderable ParentRenderable{get;set;}
		
		/// <summary>
		/// Gets or sets the position.
		/// </summary>
		/// <value></value>
		Vector3 Position{get;set;}
		
		/// <summary>
		/// Gets or sets a value indicating whether this is visible.
		/// </summary>
		/// <value>
		/// 	<c>true</c> if visible; otherwise, <c>false</c>.
		/// </value>
		bool Visible{get;set;}
		#endregion
	}

	/// <summary>
	/// Collection of IRenderable objects
	/// </summary>
	public interface IRenderableCollection
	{
		#region Methods
		/// <summary>
		/// Adds the specified renderable.
		/// </summary>
		/// <param name="renderable">Renderable.</param>
		void Add(IRenderable renderable);
		/// <summary>
		/// Removes all IRenderables in this IRenderableList.
		/// </summary>
		void Clear();
		/// <summary>
		/// Inserts IRenderable at specified index.
		/// </summary>
		/// <param name="index">Index.</param>
		/// <param name="renderable">Renderable.</param>
		void Insert(int index, IRenderable renderable);
		/// <summary>
		/// Removes IRenderable at specified index.
		/// </summary>
		/// <param name="index">Index.</param>
		/// <returns></returns>
		IRenderable RemoveAt(int index);
		/// <summary>
		/// Removes the IRenderable with specified Id.
		/// </summary>
		/// <param name="Id">Id.</param>
		/// <returns></returns>
		IRenderable RemoveId(string Id);
		#endregion

		#region Properties
		/// <summary>
		/// Gets the count of IRenderables in the list.
		/// </summary>
		/// <value></value>
		int Count{get;}
		
		/// <summary>
		/// Gets or sets the parent renderable list.
		/// </summary>
		/// <value></value>
		IRenderableCollection ParentRenderableCollection{get;set;}
		
		/// <summary>
		/// Gets or sets a value indicating whether make the collection act as a Radio Button style group in which only one object may be Visible at once.
		/// </summary>
		/// <value>
		/// 	<c>true</c> if [show only one layer]; otherwise, <c>false</c>.
		/// </value>
		bool ShowOnlyOneLayer{get;set;}
		#endregion

		#region Indexers
		/// <summary>
		/// Gets or sets the <see cref="IRenderable"/> at the specified index.
		/// </summary>
		/// <value></value>
		IRenderable this[int index] {get;set;}
		#endregion
	}

	/// <summary>
	/// Interface must be implemented in order to recieve user input.  Can be used by IRenderables and IWidgets.
	/// </summary>
	public interface IInteractive
	{
		#region Methods
		bool OnKeyDown(KeyEventArgs e);
		
		bool OnKeyUp(KeyEventArgs e);
		
		bool OnMouseDown(MouseEventArgs e);
		
		bool OnMouseEnter(EventArgs e);
		
		bool OnMouseLeave(EventArgs e);
		
		bool OnMouseMove(MouseEventArgs e);
		
		bool OnMouseUp(MouseEventArgs e);
		
		bool OnMouseWheel(MouseEventArgs e);
		#endregion
	}

	public delegate void CameraEvent(object sender, System.EventArgs e);
	
	public interface ICamera
	{
		#region Methods
		/// <summary>
		/// Setups the camera, includes the setup of the View, World, and Projection matrices
		/// </summary>
		/// <param name="appContext">App context.</param>
		void SetupCamera(IAppContext appContext);
		#endregion

		#region Events
		/// <summary>
		/// Event triggers when the camera changes position or orientation
		/// </summary>
		event CameraEvent OnCameraMove;
		#endregion

		#region Properties
		/// <summary>
		/// Gets or sets the eye position.
		/// </summary>
		/// <value></value>
		Vector3 Eye{get;set;}
		
		/// <summary>
		/// Gets or sets the look at position.
		/// </summary>
		/// <value></value>
		Vector3 LookAt{get;set;}
		
		/// <summary>
		/// Gets or sets the up vector.
		/// </summary>
		/// <value></value>
		Vector3 Up{get;set;} //could be just {0, 0, 1} with Quaternion rotations applied afterwards
		
		/// <summary>
		/// Gets or sets the eye orientation.
		/// </summary>
		/// <value></value>
		Quaternion EyeOrientation{get;set;} // Bank, Heading, and Tilt should be calculated from this
		
		/// <summary>
		/// Gets or sets the look at orientation.
		/// </summary>
		/// <value></value>
		Quaternion LookAtOrientation{get;set;} // Heading and Tilt should should be calculated from this
		
		/// <summary>
		/// Gets or sets the field-of-view of the projection matrix.
		/// </summary>
		/// <value></value>
		Angle Fov{get;set;} 
		#endregion
	}

	public interface ITerrainAccessor
	{
		#region Methods
		/// <summary>
		/// Gets the elevation at a given Latitude, Longitude, and resolution accuracy in the latitude/longitude geographic frame of reference.
		/// </summary>
		/// <param name="latitude">Latitude.</param>
		/// <param name="longitude">Longitude.</param>
		/// <param name="targetSamplesPerDegree">Target samples per degree.</param>
		/// <returns></returns>
		double GetElevationAt(double latitude, double longitude, double targetSamplesPerDegree);
		
		/// <summary>
		/// Gets the elevation array for given geographic bounding box and resolution.
		/// </summary>
		/// <param name="north">North.</param>
		/// <param name="south">South.</param>
		/// <param name="west">West.</param>
		/// <param name="east">East.</param>
		/// <param name="samples">Samples.</param>
		double[,] GetElevationArray(double north, double south, double west, double east, int samples);
		#endregion
	}

	public interface IWorld
	{
		#region Methods
		/// <summary>
		/// Gets the latitude from cartesian.
		/// </summary>
		/// <param name="cartesianPoint">Cartesian point.</param>
		/// <returns></returns>
		Angle GetLatitudeFromCartesian(Vector3 cartesianPoint);
		
		/// <summary>
		/// Gets the longitude from cartesian.
		/// </summary>
		/// <param name="cartesianPoint">Cartesian point.</param>
		/// <returns></returns>
		Angle GetLongitudeFromCartesian(Vector3 cartesianPoint);
		
		/// <summary>
		/// Gets the altitude above sea level from cartesian.
		/// </summary>
		/// <param name="cartesianPoint">Cartesian point.</param>
		/// <returns></returns>
		double GetAltitudeAboveSeaLevelFromCartesian(Vector3 cartesianPoint);
		
		/// <summary>
		/// Gets the view range from cartesian.
		/// </summary>
		/// <param name="cartesianPoint">Cartesian point.</param>
		/// <returns></returns>
		Angle GetViewRangeFromCartesian(Vector3 cartesianPoint);
		
		/// <summary>
		/// Gets the cartesian point from geographic coordinate space.
		/// </summary>
		/// <param name="latitude">Latitude.</param>
		/// <param name="longitude">Longitude.</param>
		/// <param name="altitudeAboveSeaLevel">Altitude above sea level in meters.</param>
		/// <returns></returns>
		Vector3 GetCartesianPointFromGeographic(Angle latitude, Angle longitude, double altitudeAboveSeaLevel);
		#endregion

		#region Properties
		/// <summary>
		/// Gets or sets the terrain accessor.
		/// </summary>
		/// <value></value>
		ITerrainAccessor TerrainAccessor{get;set;}
		#endregion
	}

	public interface ICameraCollection
	{
		#region Methods
		/// <summary>
		/// Adds the camera.
		/// </summary>
		/// <param name="camera">Camera.</param>
		void AddCamera(ICamera camera);
		
		/// <summary>
		/// Removes the camera.
		/// </summary>
		/// <param name="index">Index.</param>
		/// <returns></returns>
		ICamera RemoveCamera(int index);
		#endregion

		#region Events
		/// <summary>
		/// Occurs when a camera in the collection triggers an OnCameraMove event
		/// </summary>
		event CameraEvent OnCameraMove;
		#endregion

		#region Properties
		/// <summary>
		/// Gets the count of cameras in the collection.
		/// </summary>
		/// <value></value>
		int Count{get;}
		#endregion

		#region Indexers
		/// <summary>
		/// Gets the <see cref="ICamera"/> at the specified index.
		/// </summary>
		/// <value></value>
		ICamera this[int index] {get;}
		#endregion
	}

	/// <summary>
	/// Base interface for the application context that contains persistant objects accessible by anywhere in the application, such as directx devices
	/// </summary>
	public interface IAppContext
	{
		#region Properties
		/// <summary>
		/// Gets the device3d.
		/// </summary>
		/// <value></value>
		Microsoft.DirectX.Direct3D.Device Device3d{get;}
		
		/// <summary>
		/// Gets the device sound.
		/// </summary>
		/// <value></value>
		Microsoft.DirectX.DirectSound.Device DeviceSound{get;}
		
		/// <summary>
		/// Gets or sets the default drawing font.
		/// </summary>
		/// <value></value>
		Microsoft.DirectX.Direct3D.Font DefaultDrawingFont{get;set;}
		
		/// <summary>
		/// Gets or sets the root renderable.
		/// </summary>
		/// <value></value>
		IRenderable RootRenderable{get;set;}  //top level IRenderable for which all IRenderables will be children of
		
		/// <summary>
		/// Gets or sets the camera manager.
		/// </summary>
		/// <value></value>
		ICameraCollection CameraCollection{get;set;}  //all IRenderables dependant on camera view position and angles should subscribe to the OnCameraMove event
		
		/// <summary>
		/// Gets the parent control.
		/// </summary>
		/// <value></value>
		System.Windows.Forms.Control ParentControl{get;}
		
		/// <summary>
		/// Gets the root widget.
		/// </summary>
		/// <value></value>
		IWidget RootWidget{get;}
		
		/// <summary>
		/// Gets or sets the extendable objects.  This can be used to save custom objects that can be used by other elements of the program with access to IAppContext.
		/// </summary>
		/// <value></value>
		Hashtable ExtendableObjects {get;set;}
		#endregion
	}

	/// <summary>
	/// Base Interface for DirectX GUI Widgets
	/// </summary>
	public interface IWidget
	{
		#region Methods
		void Render();
		#endregion

		#region Properties
		IWidgetCollection ChildWidgets{get;set;}
		IWidget ParentWidget{get;set;}
		System.Drawing.Point Location{get;set;}
		System.Drawing.Size Size{get;set;}
		int Left{get;}
		int Top{get;}
		int Right{get;}
		int Bottom{get;}
		int Width{get;set;}
		int Height{get;set;}
		bool Enabled{get;set;}
		bool Visible{get;set;}
		object Tag{get;set;}
		#endregion
	}

	/// <summary>
	/// Collection of IWidgets
	/// </summary>
	public interface IWidgetCollection
	{
		#region Methods
		void BringToFront(int index);
		void BringToFront(IWidget widget);
		void Add(IWidget widget);
		void Clear();
		void Insert(IWidget widget, int index);
		IWidget RemoveAt(int index);
		#endregion

		#region Properties
		int Count{get;}
		#endregion

		#region Indexers
		IWidget this[int index] {get;set;}
		#endregion

	}

WorldWindow will contain an IAppContext object, which contains the persistant objects necessary for the construction of the WorldWindow environment. Among the DirectX devices, there is also a RootRenderable, a CameraManager, and a ParentWidget for which all GUI elements will reside under. IRenderables will need to subscribe to the CameraManager events to be able to update themselves as the camera moves around the environment. There is no longer an infinite updating loop, nor an infinite rendering loop. All DirectX-based GUI elements must derive the IWidget interface and add themselves to the ParentWidget. This allows a fully customizeable DX-based GUI. Also, the cameras are now free floating, meaning that they aren't necessary tied to any object, and thus, in order to get their Lat/Lon/Position, you'll need to calculate it from the Eye or Look vectors with respect to the "World" that you'd like a Lat/Lon/Distance of. It's not tough, just different. Then again, in making a camera class, it's always possible to define it so those attributes are always available, but it's just not going to be in the ICamera interface.

Solutions:

  • WorldWindSDK
    • produces API (version specific) DLLs
    • the idea is that this doesn't change often and should more or less be left alone.
  • WorldWindow
    • produces WorldWindow.dll
    • uses WorldWindSDK DLLs as base interfaces
  • WorldWind
    • produces WorldWind.exe
    • uses WorldWindow.dll

-- More to come...Feel free to comment

Personal tools