Kristoffer's tidbits : Virtual Earth 3D Plugins

How does Virtual Earth 3D find and load plugins?

Kristoffer — Fri, 07 Dec 2007 21:45:00 GMT

On startup VE3D looks in the Plugins folder of the install directory (ProgramFiles\Virtual Earth 3D) and iterates through the assemblies in each subfolder of Plugins. A plugin named Sample would install itself as C:\Program Files\Virtual Earth 3D\Plugins\Sample\Sample.dll. Note that this folder doesn't exist by default so your plugin installer will need to create it.

Next each assembly is probed for classes that descend from Microsoft.MapPoint.PlugIns.PlugIn. For security reasons only assemblies that are in the GAC are allowed to run. The good news is that we are investigating allowing partially trusted plugins for our next release. This means you will be able to visit a website and have it load its own plugins to add new functionality to VE3D without forcing you to go through an install process. Since we're still in the early parts of our next release I don't know for sure if this will make the cut but it is something we would like to add.

Using a plugin to add a billboard to Virtual Earth 3D

Kristoffer — Wed, 14 Nov 2007 23:10:00 GMT

To add objects to the VE3D world we need to create our own actor that knows how to render itself.

Actors descend from Microsoft.MapPoint.Rendering3D.Steps.Actors.Actor and must override the Render method. When it comes time to render a frame, all actors have their Render method called to queue up renderable objects. To show a billboard we'll create a BillboardActor and use a SpriteGraphicsObject to render our image.

        public BillboardActor(LatLonAlt position)
        {
            this.texture = Texture.FromResource(this.GetType().Assembly, "VirtualEarth3DSamplePlugins.Billboard.Flower.png");
 
            this.billboard = new SpriteGraphicsObject();
            this.billboard.Texture = this.texture;
            this.billboard.Mode = SpriteMode.Billboard;
            this.billboard.Scale = new Vector2D(1000, 1000);
            this.billboard.Color = Color.White;
            this.billboard.AlphaEnable = true;
            this.billboard.Position = position.GetVector();
        }

 
        public override void Render(Microsoft.MapPoint.Rendering3D.Scene.SceneState sceneState)
        {
            RenderQueues renderQueues = sceneState.GetData<RenderQueues>();
 
            renderQueues.AddAlphaRenderable(0, this.billboard);
        }

Once we have our actor we just need to add it to the ActorManager so it knows to start rendering it. We can do this in our Activate method on the plugin.

            LatLonAlt position = LatLonAlt.CreateUsingDegrees(46.849743288383046, -121.7498016357422, 5000);
            // Add the actor at the specified position
            this.Host.Actors.Add(new BillboardActor(position));

You can browse the source code for the actor and the plugin online or download the entire project.
BillboardActor.cs | BillboardPlugin.cs
Download project

Creating a Hello World plugin for Virtual Earth 3D

Kristoffer — Tue, 13 Nov 2007 20:33:00 GMT

With latest release of the Virtual Earth 3D release we now support loading plugins to perform additional functionality not implemented in the main product. Two new features of the release are even implemented as plugins (bird's eye photos and user created models).

To get you started with creating your own plugin for VE3D here's a short starter guide using Visual Studio 2005.

Create a new C# Class Library project, call it HelloWorld.
Add references to the following assemblies located in C:\Program Files\Virtual Earth 3D:
- Microsoft.MapPoint.Rendering3D.dll
- Microsoft.MapPoint.Rendering3D.Utility.dll
Rename Class1.cs to HelloWorldPlugin.cs and paste the following code over the file:

using System;

using System.Collections.Generic;

using System.Text;

using Microsoft.MapPoint.PlugIns;

using Microsoft.MapPoint.Rendering3D;

namespace VirtualEarth3DSamplePlugins.HelloWorld

{

    public class HelloWorldPlugin : PlugIn

    {

        #region Constructor

        public HelloWorldPlugin(Host host)

            : base(host)

        {

        }

        #endregion

        #region Overrides

        public override void Activate(object activationObject)

        {

            this.Host.Notifications.Display("Hello world!");

            base.Activate(activationObject);

        }

        public override string Name

        {

            get

            {

                return "HelloWorldPlugin";

            }

        }

        #endregion

    }

}
Go to Project Properties, Signing, check Sign the assembly and create a new key to sign your project with. Only plugins that are in the GAC will be granted permissions to run and only strongly named assemblies may be placed in the GAC.
Build your project and copy HelloWorld.dll to a new folder named C:\Program Files\Virtual Earth 3D\Plugins\HelloWorld. From a Visual Studio 2005 Command Prompt run
gacutil -i "C:\Program Files\Virtual Earth 3D\Plugins\HelloWorld\HelloWorld.dll"

Now start up 3D mode on maps.live.com and you should see a notification upon startup from the hello world plugin.

That's it for creating a simple plugin. If you want to explore further on your own the Host object contains all the interfaces for a plugin to communicate with VE3D.

Mandatory disclaimer so I don't get into trouble: creating plugins is not officially supported.