Silverlight Toolkit (December 2011) for Silverlight 5–What’s new?

The new version of the Silverlight Toolkit (December 2011) for Silverlight 5 is out and you can grab it here:

https://silverlight.codeplex.com/releases/view/78435

Update: Babylon Engine now uses Silverlight 5 Toolkit: https://code.msdn.microsoft.com/Babylon-3D-engine-f0404ace

I had the pleasure of working on this version and I’m pleased to write this article to help you discover how the Toolkit enhances Silverlight 5 with the following features:

1. Seamless integration of 3D models and other assets with the Content Pipeline
2. New Visual Studio templates for creating:
   1. Silverlight 3D Application
   2. Silverlight 3D Library
   3. Silverlight Effect
3. New samples to demo these features

Seamless integration with the Content Pipeline

The toolkit comes with a new assembly : Microsoft.Xna.Framework.Content.dll. This assembly allows you to load assets from the .xnb file format (produced by the Content Pipeline).

Using the new Visual Studio templates (which I will describe later), you can now easily port existing 3D projects directly to Silverlight 5!

Microsoft.Xna.Framework.Content.dll assembly will add the following classes to Silverlight 5:

• ContentManager
• Model
• SpriteFont and SpriteBatch

The toolkit comes also with the Microsoft.Xna.Framework.Tookit.dll assembly which will add the following classes to Silverlight 5:

• SilverlightEffect
• Mouse, MouseState
• Keyboard, KeyboardState

ContentManager

The documentation for this class can be found here:
https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.content.contentmanager.aspx

The ContentManager class is the representative for the Content Pipeline inside your code. It is responsible for loading objects from .xnb files.

To create a ContentManager you just have to call the following code:

1. 
   ContentManager contentManager = new ContentManager(null, “Content”);
   

There are restrictions for this class : The ContentManager for Silverlight can only support one Content project and the RootDirectory must be set to “Content”

Using it is really simple because it provides a simple Load method which can be used to create your objects:

1. 
   // Load fonts
   


2. 
   hudFont = contentManager.Load<SpriteFont>(“Fonts/Hud”);
   


3. 
    
   


4. 
   // Load overlay textures
   


5. 
   winOverlay = contentManager.Load<Texture2D>(“Overlays/you_win”);
   


6. 
    
   


7. 
   // Music
   


8. 
   backgroundMusic = contentManager.Load<SoundEffect>(“Sounds/Music”);
   

Model

The documentation for this class can be found here:
https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.graphics.model.aspx

The model class has the same API as in XNA 4 and it will allow you to load and render 3D models from XNB files:

1. 
   // Draw the model.
   


2. 
   Model tankModel = content.Load<Model>(“tank”);
   


3. 
   tankModel.Draw();
   

You can also use bones if your model supports them:

1. 
   Model tankModel = content.Load<Model>(“tank”);
   


2. 
   tankModel.Root.Transform = world;
   


3. 
   tankModel.CopyAbsoluteBoneTransformsTo(boneTransforms);
   


4. 
    
   


5. 
   // Draw the model.
   


6. 
   foreach (ModelMesh mesh in tankModel.Meshes)
   


7. 
   {
   


8. 
       foreach (BasicEffect effect in mesh.Effects)
   


9. 
       {
   


10. 
            effect.World = boneTransforms[mesh.ParentBone.Index];
    


11. 
            effect.View = view;
    


12. 
            effect.Projection = projection;
    


13. 
     
    


14. 
            effect.EnableDefaultLighting();
    


15. 
        }
    


16. 
     
    


17. 
        mesh.Draw();
    


18. 
    }
    

You can import models using .x or .fbx format:

And thanks to the FBX importer, you can also import .3ds, .obj, .dxf and even Collada.

SpriteFont & SpriteBatch

The documentation for these classes can be found here:
https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.graphics.spritebatch.aspx
https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.graphics.spritefont.aspx

The SpriteBatch class is used to display 2D textures on top of the render. You can use them for displaying a UI or sprites.

1. 
   SpriteBatch spriteBatch = new SpriteBatch(graphicsDevice);
   


2. 
    
   


3. 
   spriteBatch.Begin(SpriteSortMode.Immediate, BlendState.Opaque);
   


4. 
    
   


5. 
   spriteBatch.Draw(texture, new Rectangle(0, 0, width, height), Color.White);
   


6. 
    
   


7. 
   spriteBatch.End();
   

As you can see, SpriteBatch only needs a texture to display.

SpriteFont allows you to use sprites to display text.

1. 
   SpriteFont hudFont = contentManager.Load<SpriteFont>(“Fonts/Hud”);
   


2. 
   spriteBatch.DrawString(hudFont, value, position + new Vector2(1.0f, 1.0f), Color.Black);
   


3. 
   spriteBatch.DrawString(hudFont, value, position, color);
   

SpriteFont relies on SpriteBatch to draw and needs a font definition from the ContentManager:

SilverlightEffect

The toolkit introduces a new class called SilverlightEffect which can be used to apply .fx files.

It also support .slfx which is the default extension. There is no difference between .slfx and .fx but as XNA Effect Processor is already associated with .fx, the Silverlight Content Pipeline had to select another one.

You can now define a complete effect inside a Content project and use it for rendering your models.

To do so:

• Create a .fx file with a least one technique
• Shader entry points must be parameterless
• Define render states

For example here is a simple .fx file:

1. 
   float4x4 WorldViewProjection;
   


2. 
   float4x4 World;
   


3. 
   float3 LightPosition;
   


4. 
    
   


5. 
   // Structs
   


6. 
   struct VS_INPUT
   


7. 
   {
   


8. 
       float4 position                : POSITION;
   


9. 
       float3 normal                : NORMAL;
   


10. 
        float4 color                : COLOR0;
    


11. 
    };
    


12. 
     
    


13. 
    struct VS_OUTPUT
    


14. 
    {
    


15. 
        float4 position                : POSITION;
    


16. 
        float3 normalWorld            : TEXCOORD0;
    


17. 
        float3 positionWorld        : TEXCOORD1;
    


18. 
        float4 color                : COLOR0;       
    


19. 
    };
    


20. 
     
    


21. 
    // Vertex Shader
    


22. 
    VS_OUTPUT mainVS(VS_INPUT In)
    


23. 
    {
    


24. 
        VS_OUTPUT Out = (VS_OUTPUT);
    


25. 
     
    


26. 
        // Compute projected position
    


27. 
        Out.position = mul(In.position, WorldViewProjection);
    


28. 
     
    


29. 
        // Compute world normal
    


30. 
        Out.normalWorld = mul(In.normal,(float3x3) WorldViewProjection);
    


31. 
     
    


32. 
        // Compute world position
    


33. 
        Out.positionWorld = (mul(In.position, World)).xyz;
    


34. 
     
    


35. 
        // Transmit vertex color
    


36. 
        Out.color = In.color;
    


37. 
     
    


38. 
        return Out;
    


39. 
    }
    


40. 
     
    


41. 
    // Pixel Shader
    


42. 
    float4 mainPS(VS_OUTPUT In) : COLOR
    


43. 
    {
    


44. 
        // Light equation
    


45. 
        float3 lightDirectionW = normalize(LightPosition – In.positionWorld);
    


46. 
        float ndl = max(, dot(In.normalWorld, lightDirectionW));
    


47. 
     
    


48. 
        // Final color
    


49. 
        return float4(In.color.rgb * ndl, 1);
    


50. 
    }
    


51. 
     
    


52. 
    // Technique
    


53. 
    technique MainTechnique
    


54. 
    {
    


55. 
        pass P0
    


56. 
        {
    


57. 
            VertexShader = compile vs_2_0 mainVS(); // Must be a non-parameter entry point
    


58. 
            PixelShader = compile ps_2_0 mainPS(); // Must be a non-parameter entry point
    


59. 
        }
    


60. 
    }
    

The Toolkit will add required processors to the Content Pipeline in order to create the .xnb file for this effect:

To use this effect, you just have to instantiate a new SilverlightEffect inside your code:

1. 
   mySilverlightEffect = scene.ContentManager.Load<SilverlightEffect>(“CustomEffect”);
   

Then, you can retrieve effect’s parameters:

1. 
   worldViewProjectionParameter = mySilverlightEffect.Parameters[“WorldViewProjection”];
   


2. 
   worldParameter = mySilverlightEffect.Parameters[“World”];
   


3. 
   lightPositionParameter = mySilverlightEffect.Parameters[“LightPosition”];
   

To render an object with your effect, it is the same code as in XNA 4:

1. 
   worldParameter.SetValue(Matrix.CreateTranslation(1, 1, 1));
   


2. 
   worldViewProjectionParameter.SetValue(WorldViewProjection);
   


3. 
   lightPositionParameter.SetValue(LightPosition);
   


4. 
   foreach (var pass in mySilverlightEffect.CurrentTechnique.Passes)
   


5. 
   {
   


6. 
       // Apply pass
   


7. 
       pass.Apply();
   


8. 
    
   


9. 
       // Set vertex buffer and index buffer
   


10. 
        graphicsDevice.SetVertexBuffer(vertexBuffer);
    


11. 
        graphicsDevice.Indices = indexBuffer;
    


12. 
     
    


13. 
        // The shaders are already set so we can draw primitives
    


14. 
        graphicsDevice.DrawIndexedPrimitives(PrimitiveType.TriangleList, 0, 0, VerticesCount, 0, FaceCount);
    


15. 
    }
    

Texture2D, TextureCube & SoundEffect

Silverlight 5 provides Texture2D, TextureCube and SoundEffect classes. With the Toolkit, you will be able to load them from the ContentManager:

1. 
   // Load overlay textures
   


2. 
   winOverlay = contentManager.Load<Texture2D>(“Overlays/you_win”);
   


3. 
    
   


4. 
   // Music
   


5. 
   backgroundMusic = contentManager.Load<SoundEffect>(“Sounds/Music”);
   

Mouse and Keyboard

In order to facilitate porting existing 3D applications and to accommodate polling input application models, we also added partial support for Microsoft.Xna.Framework.Input namespace.

So you will be able to request MouseState and KeyboardState everywhere you want:

1. 
   public MainPage()
   


2. 
   {
   


3. 
       InitializeComponent();
   


4. 
    
   


5. 
       Mouse.RootControl = this;
   


6. 
       Keyboard.RootControl = this;
   


7. 
   }
   

However, there is a slight difference from original XNA on other endpoints: you have to register the root control which will provide the events for Mouse and Keyboard. The MouseState positions will be relative to the upper left corner of this control:

1. 
   private void myDrawingSurface_Draw(object sender, DrawEventArgs e)
   


2. 
   {
   


3. 
       // Render scene
   


4. 
       scene.Draw();
   


5. 
    
   


6. 
       // Let’s go for another turn!
   


7. 
       e.InvalidateSurface();
   


8. 
    
   


9. 
       // Get mouse and keyboard state
   


10. 
        MouseState mouseState = Mouse.GetState();
    


11. 
        KeyboardState keyboardState = Keyboard.GetState();
    


12. 
     
    


13. 
        …
    


14. 
    }
    

The MouseState and KeyboardState are similar to XNA versions:

• https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.input.mousestate.aspx
• https://msdn.microsoft.com/en-us/library/microsoft.xna.framework.input.keyboardstate.aspx

Extensibility

Silverlight Content Pipeline can be extended the same way as the XNA Content Pipeline on other endpoints. You can provide your own implementation for loading assets from elsewhere than the embedded .xnb files.

For example you can write a class that will stream .xnb from the network. To do so, you have to  inherit from ContentManager and provide your own implementation for OpenStream:

1. 
   public class MyContentManager : ContentManager
   


2. 
   {
   


3. 
       public MyContentManager() : base(null)
   


4. 
       {
   


5. 
          
   


6. 
       }
   


7. 
    
   


8. 
       protected override System.IO.Stream OpenStream(string assetName)
   


9. 
       {           
   


10. 
            return base.OpenStream(assetName);
    


11. 
        }
    


12. 
    }
    

You can also provide our own type reader. Here is for example the custom type reader for SilverlightEffect:

1. 
   ///
   
   


2. 
   /// Read SilverlightEffect.
   


3. 
   ///
   


4. 
   public class SilverlightEffectReader : ContentTypeReader<SilverlightEffect>
   


5. 
   {
   


6. 
       ///
   
   


7. 
       /// Read and create a SilverlightEffect
   


8. 
       ///
   


9. 
       protected override SilverlightEffect Read(ContentReader input, SilverlightEffect existingInstance)
   


10. 
        {
    


11. 
            int techniquesCount = input.ReadInt32();
    


12. 
            EffectTechnique[] techniques = new EffectTechnique[techniquesCount];
    


13. 
     
    


14. 
            for (int techniqueIndex = 0; techniqueIndex < techniquesCount; techniqueIndex++)
    


15. 
            {
    


16. 
                int passesCount = input.ReadInt32();
    


17. 
                EffectPass[] passes = new EffectPass[passesCount];
    


18. 
     
    


19. 
                for (int passIndex = 0; passIndex < passesCount; passIndex++)
    


20. 
                {
    


21. 
                    string passName = input.ReadString();
    


22. 
     
    


23. 
                    // Vertex shader
    


24. 
                    int vertexShaderByteCodeLength = input.ReadInt32();
    


25. 
                    byte[] vertexShaderByteCode = input.ReadBytes(vertexShaderByteCodeLength);
    


26. 
                    int vertexShaderParametersLength = input.ReadInt32();
    


27. 
                    byte[] vertexShaderParameters = input.ReadBytes(vertexShaderParametersLength);
    


28. 
     
    


29. 
                    // Pixel shader
    


30. 
                    int pixelShaderByteCodeLength = input.ReadInt32();
    


31. 
                    byte[] pixelShaderByteCode = input.ReadBytes(pixelShaderByteCodeLength);
    


32. 
                    int pixelShaderParametersLength = input.ReadInt32();
    


33. 
                    byte[] pixelShaderParameters = input.ReadBytes(pixelShaderParametersLength);
    


34. 
     
    


35. 
                    MemoryStream vertexShaderCodeStream = new MemoryStream(vertexShaderByteCode);
    


36. 
                    MemoryStream pixelShaderCodeStream = new MemoryStream(pixelShaderByteCode);
    


37. 
                    MemoryStream vertexShaderParametersStream = new MemoryStream(vertexShaderParameters);
    


38. 
                    MemoryStream pixelShaderParametersStream = new MemoryStream(pixelShaderParameters);
    


39. 
     
    


40. 
                    // Instanciate pass
    


41. 
                    SilverlightEffectPass currentPass = new SilverlightEffectPass(passName, GraphicsDeviceManager.Current.GraphicsDevice, vertexShaderCodeStream, pixelShaderCodeStream, vertexShaderParametersStream, pixelShaderParametersStream);
    


42. 
                    passes[passIndex] = currentPass;
    


43. 
     
    


44. 
                    vertexShaderCodeStream.Dispose();
    


45. 
                    pixelShaderCodeStream.Dispose();
    


46. 
                    vertexShaderParametersStream.Dispose();
    


47. 
                    pixelShaderParametersStream.Dispose();
    


48. 
     
    


49. 
                    // Render states
    


50. 
                    int renderStatesCount = input.ReadInt32();
    


51. 
     
    


52. 
                    for (int renderStateIndex = 0; renderStateIndex < renderStatesCount; renderStateIndex++)
    


53. 
                    {
    


54. 
                        currentPass.AppendState(input.ReadString(), input.ReadString());
    


55. 
                    }
    


56. 
                }
    


57. 
     
    


58. 
                // Instanciate technique
    


59. 
                techniques[techniqueIndex] = new EffectTechnique(passes);
    


60. 
            }
    


61. 
     
    


62. 
            return new SilverlightEffect(techniques);
    


63. 
        }
    


64. 
    }
    

 

New Visual Studio templates

The toolkit will install two new project templates and a new item template:

Silverlight3DApp

This template will produce a full working Silverlight 3D application.

The new solution will be composed of 4 projects:

• Silverlight3DApp : The main project
• Silverlight3DAppContent : The content project attached with the main project
• Silverlight3DWeb : The web site that will display the main project
• Silverlight3DWebContent : A content project attached to the website if you want to stream your .xnb from the website instead of using embedded ones. This will allow you distribute a smaller .xap.

The main project (Silverlight3DApp) is built around two objects:

• A sceneobject which
  • Create the ContentManager
  • Handle the DrawingSurface Draw event
• A cubeobject
  • Create a vertex buffer and index buffer
  • Use the ContentManager to retrieve a SilverlightEffect (Customeffect.slfx) from the content project
  • Configure and use the SilverlightEffect to render

Silverlight3DLib

This template will produce a Silverlight Library without any content but with all Microsoft.Xna.Framework references set:

And the resulting project will look like:

SilverlightEffect

This item template can be used inside a Content project to add a custom .slfx file that will work with SilverlightEffect class:

The file content will be the following:

1. 
   float4x4 World;
   


2. 
   float4x4 View;
   


3. 
   float4x4 Projection;
   


4. 
    
   


5. 
   // TODO: add effect parameters here.
   


6. 
    
   


7. 
   struct VertexShaderInput
   


8. 
   {
   


9. 
       float4 Position : POSITION0;
   


10. 
     
    


11. 
        // TODO: add input channels such as texture
    


12. 
        // coordinates and vertex colors here.
    


13. 
    };
    


14. 
     
    


15. 
    struct VertexShaderOutput
    


16. 
    {
    


17. 
        float4 Position : POSITION0;
    


18. 
     
    


19. 
        // TODO: add vertex shader outputs such as colors and texture
    


20. 
        // coordinates here. These values will automatically be interpolated
    


21. 
        // over the triangle, and provided as input to your pixel shader.
    


22. 
    };
    


23. 
     
    


24. 
    VertexShaderOutput VertexShaderFunction(VertexShaderInput input)
    


25. 
    {
    


26. 
        VertexShaderOutput output;
    


27. 
     
    


28. 
        float4 worldPosition = mul(input.Position, World);
    


29. 
        float4 viewPosition = mul(worldPosition, View);
    


30. 
        output.Position = mul(viewPosition, Projection);
    


31. 
     
    


32. 
        // TODO: add your vertex shader code here.
    


33. 
     
    


34. 
        return output;
    


35. 
    }
    


36. 
     
    


37. 
    float4 PixelShaderFunction(VertexShaderOutput input) : COLOR0
    


38. 
    {
    


39. 
        // TODO: add your pixel shader code here.
    


40. 
     
    


41. 
        return float4(1, , , 1);
    


42. 
    }
    


43. 
     
    


44. 
    technique Technique1
    


45. 
    {
    


46. 
        pass Pass1
    


47. 
        {
    


48. 
            // TODO: set renderstates here.
    


49. 
     
    


50. 
            VertexShader = compile vs_2_0 VertexShaderFunction();
    


51. 
            PixelShader = compile ps_2_0 PixelShaderFunction();
    


52. 
        }
    


53. 
    }
    

New samples to demo these features

Finally, to help you discover and learn all these features, we added some cools samples:

Bloom

This sample shows you how to use sprites to accomplish post-processing effects such as “bloom”. It also uses the Content Pipeline to import a tank model from a .fbx file.

CustomModelEffect

This sample shows you how custom effects can be applied to a model using the Content Pipeline.

Generated geometry

This sample shows how 3D models can be generated by code during the Content Pipeline build process.

Particles

This sample introduces the concept of a particle system, and shows how to draw particle effects using SpriteBatch. Two particle effects are demonstrated: an explosion and a rising plume of smoke:

Primitives3D

This sample provides easily reusable code for drawing basic geometric primitives:

Platformer

This sample is a complete game with 3 levels provided (you can easily add yours). It shows the usage of SpriteBatch, SpriteFont and SoundEffect inside a platform game. It also uses Keyboard class to control the player.

SimpleAnimation

This sample shows how to apply program controlled rigid body animation to a 3D model loaded with the ContentManager:

Skinning

This sample shows how to process and render a skinned character model using the Content Pipeline.

Conclusion

As you noticed, all these new additions to the Silverlight Toolkit are made to make it easy to get started with new Silverlight 3D features by providing developer tools to improve usability and productivity.

You can now easily start a new project that leverages both concepts of XNA and Silverlight. It becomes easy to work with 3D concepts and resources like shaders, model, sprites, effects, etc…

We also try to reduce the effort to port existing 3D applications to Silverlight.

So now it’s up to you to discover the wonderful world of 3D using Silverlight 5!