Virtual Earth 3D team blog : Actor

X File bulk display

NikolaiF — Mon, 21 Sep 2009 00:42:00 GMT

I was asked the other day about how to load multiple x file -based models into VE3D without having to place each one manually. I've written up a sample here. The idea is more or less a fusion of the existing ActorDataSource and XFile samples, using the actor from the XFile sample rather than the bunnies. I've also mocked up a very simple data file that contains placement information, rather than generating data on the fly as for the bunnies.

The way I've done this, the parsing code for the x files is done in the actor. In this way, swapping out file formats should be straightforward so long as you have parsing code for it (sorry, only x files are directly implemented in the engine, but the results of any parse should still be easily convertible into VE3D graphics objects).

For the sake of simplicitly I did do one thing wrong. The flow of the code is like this: multiple background threads all execute QueryPrimitivesInternal at the same time, and when they are finished, they move through a lock into ActorBuilder. They are still on background threads, but they now execute serially. So, really the data retrieval (in this case, loading from resources, but probably a network request) and the parsing, as appropriate, should happen in QueryPrimitivesInternal, and the action in ActorBuilder should be kept to a minimum. I violated this rule in the sample code for the sake of illustration, but you should be aware of it.

Finally, an important consideration is level of detail. Dense and numerous models can slow down loading and rendering. DataSources take advantage of the ActorBounds and scale concepts, such that it is possible to use simplified models at certain LODs, and switch to more detailed as the user zooms in. If your needs are less extreme, then you can simply use scale to cause models to stop rendering when not in view, and at a certain distance, which is what I have done in the sample.

Have fun!

Actor data source questions

NikolaiF — Sun, 26 Jul 2009 21:06:00 GMT

I just fielded a few good questions via email about actor data sources, and thought it would make a good post.

Actor data sources are a way of getting little bits of your code (actors) into the world, handing spatial indexing and cache management for you. When each actor is in view, they are given the opportunity to execute code in the Render and Update functions. When the cache is full and an actor is evicted, they again may execute code in the OnRemove function.

You create them by implementing a DataSource with usage Actor, and an ActorBuilder which translates the Primitives returned into Actor objects, along with information like what areas of the Earth the actors should be used in, as an ActorBounds object. All of this can be seen in the ActorDataSource sample.

In the sample, however, only one Primitive is returned per request, and only one Actor. What if you want more? The important thing to know is that there has to be a 1-1 correspondence between Primitives and Actors *. You must create one Actor for every Primitive used. If you create more than one Actor for a single Primitive, only one will appear.

The reason for this is the Actor update story. It is possible to update an Actor already in the system by two methods. When an Actor is updated, the PrimitiveId from the passed-in primitive is used to find and update the actor in question. If you add multiple actors per primitive, an ambiguity arises as to what you actually want to do.

It is possible to resolve this ambiguity by creating "nested" actors. This is simple. Just create the actors you want, and then a "container"

*: actually you can create a single Actor with multiple Primitives, but I don't want to confuse the issue for now.

Updating an Actor:

Expiration. On the Entity attached to your primitive, add a property "ExpiresInSeconds":

e.EntityTypes["bunny"].Properties.Create("ExpiresInSeconds", typeof(double));

...

entitySpec.Properties.SetValue("ExpiresInSeconds", 10.0);

Your QueryPrimitivesInternal function will be called again for every area the affected Actors live, and OnRemove will be called for the expiring Actors.

Manual. You can specify a specific PrimitiveId to update using OnDataChanged in your source DataSource.

PrimitiveIdWriteableCollection wc = new PrimitiveIdWriteableCollection();
wc.Add(new BunnyPrimitiveId(this, tile));
OnDataChanged(new SpatialExtent(null, null, wc.GetReadOnlyCopy()));

You must also implement the QueryPrimitivesByIdsInternal function. A collection of ids is provided, and you must return an array of Primitives that matches the input (so, the first item in the id collection should result in a Primitive at array index 0, etc). If an element of the array is left null, that means to delete the Actor corresponding to that PrimitiveId. Your ActorBuilder is then called to allow you to create the new replacement Actors.

You can also specify a region of the Earth to update in the SpatialExtent, but update by entity is not supported. Updating very large areas can be expensive, so use spatial regions with care. Update by PrimitiveId is the most efficient.

Animated Textures

NikolaiF — Wed, 19 Nov 2008 03:55:00 GMT

In addition to using dynamic buffers to animate geometry, you can also animate the textures on geometry. This is accomplished by using BitmapProvider. A BitmapProvider at its simplest is just a wrapper for a Bitmap, which can be used as the icon for a pushpin or the data for a texture that should be applied to geometry that you create in an Actor. In fact, if you just have a single image you can use SingleBitmapProvider. You expose this Bitmap via the CurrentImage property. You also have to provide the size of the image upfront using ImageSize. If you want to change the texture, the system polls the NewImageAvailable property. If you return true, the system re-reads CurrentImage and copies data into the display texture. When it is done, it calls OperationCompleted.

See it in action!

In this sample, we use a pushpin created with our own BitmapProvider. This provider reads the previous screen buffer, creating an infinite mirror effect. We could actually clean this sample up a bit in two ways: by implementing HasFrequentUpdates to return true (causing it to animate continuously) and removing the call to Host.NeedUpdate, and by implementing OperationCompleted to dispose current.

In a more realistic example, we might have a thread that periodically queries the url of a traffic cam. When the image data arrives, set NewImageAvailable to true, provide the new image, and in OperationCompleted signal the query thread to get a new image.

For a demonstration of how to do this using Actors, copy the ScreenshotProvider class from AnimatedPins to BezierSurface, and change SurfacePlugIn.cs, line 91, to:

Texture t = Texture.FromBitmapProvider(new ScreenshotProvider(this.Host));

and presto! you get the same effect.

Finally, SingleImageProvider has code built in to deal with animated gifs. Simply create a bitmap with the animated gif, hand it to SingleImageProvider, that to your pin or Texture, and everything should go on its own from there.

Get the code!

Animation Redux

NikolaiF — Tue, 11 Nov 2008 04:05:00 GMT

This sample was released before, but didn't have a version that could run on the web without an install.

The new version in the samples pack is almost exactly the same, so I won't go over it again in detail. This post is just to show it off interactively.

See it in action!

When the page loads, press "S" after the text appears. You can then grab the green balls with the mouse to deform the surface. Left-click and drag causes it to deform to the new location and then slowly return; right-click and drag causes it to move to the new shape permanently.

Actors and DataSources

NikolaiF — Mon, 27 Oct 2008 23:51:00 GMT

In this sample, we create a DataSource, which is a class that can be used for large-scale data sets. It provides hooks into the system's spatial index, memory cache, and background data threads. Data from the DataSource will only be requested when it is in view, and will be automatically cached according to how often it is used and how much memory it consumes. The DataSource we create is a purely generated one consisting of a large number of animated bunnies spread evenly across the globe, and would be impossibly large to try to deal with all at once.

See it in action!

When the PlugIn is Activated, the ActorDataSource is created and added to the system. When we create the DataSource we set up its Ontology, which is a system for defining the type of data the DataSource contains.

The next time the Camera Query runs, a set of areas in the Spatial Index that are in view are determined, called tiles. Each tile is sent as a lat/long bounding box to the Data Threads, which call all added DataSources, including ours. The entry point here is QueryPrimitivesInternal. In this function we would normally do some sort of query to a backend, such as a SQL database or the network, but for simplicity we simply create a BunnyPrimitive in the center of the query region. A primitive is a piece of data that represents a thing in the world, in the case a Bunny, but is not itself an Actor. When we return the Primitive, it is passed to our ActorBuilder, called BunnyBuilder. This creates actual Actors which can render or react to the data represented by each Primitive. Each Actor also needs an ActorBounds, which represents a spatial area that, when in view, should cause it to render. When this happens each Actor's Update and Render functions are called on the Render Thread just like normal Actors.

Get the code!