The system has two core components:

• A server application, which is a Win32 console application that handles incoming queries and returns data to the connected clients. This application runs on the desktop machine with the connected sensor.
• The Windows Phone application that sends requests to the target server and can trigger a variety of pre-programmed commands.

The Basics

Hardware and Communication Infrastructure

One of the most important parts of the project is the signal capture and replication hardware. For the purposes of this project, I decided to use a dual-mode Phidgets IR sensor. It supports both IR code capture and subsequent replication. From a user’s perspective, this device also eliminates a substantial code-learning overhead as well as the potential error rate. Instead of searching for a device-specific hexadecimal sequence that later has to be transformed in a working IR code, the user simply has to point his remote control at the sensor and press the button that he wants accessible from a mobile device. Given that the capturing software is running on the target machine, once the sensor detects that a code can be repeated within an acceptable precision range, it will be automatically captured and stored, with all required transformations worked out in the backend using the free Phidgets SDK.

Even though I can, I don’t have to handle the binary code content received through the sensor—the Phidgets .NET libraries carry built-in types that contain all the processed metadata that I will discuss later in this article.

This sensor is connected through a USB port to a machine that acts as a communication gateway. This server should have port 6169 open for inbound connections.

NOTE: The port number can be changed, but you have to keep it consistent between your server and client applications.

The communication between the phone and the computer running the client is performed via a TCP channel—sockets are used to perform the initial connections and serialized data transfer. You can see the generalized data flow between the devices that are involved in the procedure in the graphic below:

The server (desktop client) handles the local storage and release of all incoming IR codes. The mobile client has to know the location of the server—once specified and confirmed, it can send one of the pre-defined commands to it and either query the server for existing command groups (sets) or invoke one of the stored IR codes. When I pass data between devices, I use JSON for the serializable components. The data is also processed before being sent in order to speed-up the process—for example, on the server side the sets are serialized together with the associated codes. Like this:

[
{
    "Name":"batman",
    "IsList":false,
    "Commands":[
    {
        "Name":"test command",
        "Code":{
            "Mask":{
                "BitSize":12,
                "CodeData":"AAA="
            },
            "BitSize":12,
            "Encoding":2,
            "CarrierFrequency":38000,
            "DutyCycle":50,
            "Gap":44761,
            "Header":[
            2374,
            606
            ],
            "CodeData":"DJA=",
            "MinRepeat":5,
            "One":[
            1189,
            606
            ],
            "Repeat":null,
            "Trail":0,
            "Zero":[
            582,
            606
            ]
        }
    },
    {
        "Name":"turn off",
        "Code":{
            "Mask":{
                "BitSize":12,
                "CodeData":"AAA="
            },
            "BitSize":12,
            "Encoding":2,
            "CarrierFrequency":38000,
            "DutyCycle":50,
            "Gap":44770,
            "Header":[
            2360,
            613
            ],
            "CodeData":"DJA=",
            "MinRepeat":5,
            "One":[
            1169,
            613
            ],
            "Repeat":null,
            "Trail":0,
            "Zero":[
            585,
            613
            ]
        }
    }
    ]
}
]

The inherent problem with the JSON data above is the fact that the phone client does not need the information related to the code binary sequence and all the metadata that goes with it. So it is effectively stripped down and reduced to the names of the sets (when a list of sets is requested) and commands (when a list of commands is requested).

The Data Model

As you saw from the description above, the server organizes individual infrared codes in sets. A single set is a bundle of codes that may or may not be related to each other—ultimately, this is the user’s decision. A good example of using sets is organizing IR commands by rooms, devices or code types. Each set has a unique name on the server, therefore eliminating the possibility of a request conflict.

Each set stores individual commands built around the Command model:

namespace Coding4Fun.MissionControl.API.Models 
{ 
    public class Command 
    { 
        public Command() 
        { 
        } 
    
    public string Name { get; set; }     
    public SerializableIRCode Code { get; set; } 
    } 
}

Despite the obvious Name property, you can see that I am using a SerializableIRCode instance that is specific to each model. Before going any further, I need to mention that the Phidgets SDK offers the IRLearnedCode model to store code contents. I could have used it instead, but there is an issue that prevents me from doing that—there is no public constructor defined for IRLearnedCode, therefore there is no way to serialize it, either with the built-in .NET serialization capabilities or JSON.NET, which I am using in the context of the project.

Instead, I have this:

using Phidgets; 
namespace Coding4Fun.MissionControl.API.Models 
{     
    public class SerializableIRCode     
    {         
        public SerializableIRCode()         
        { 
            
        } 
        
    IRLearnedCode code;         
    public ToggleMask Mask { get; set; } 
    public int BitSize { get; set; } 
    public Phidgets.IRCodeInfo.IREncoding Encoding { get; set; } 
    public int CarrierFrequency { get; set; } 
    public int DutyCycle { get; set; } 
    public int Gap { get; set; } 
    public int[] Header { get; set; } 
    public byte[] CodeData { get; set; } 
    public int MinRepeat { get; set; } 
    public int[] One { get; set; } 
    public int[] Repeat { get; set; } 
    public int Trail { get; set; } 
    public int[] Zero { get; set; } 
    }     
}

It is an almost identical 1:1 copy of the original class, storing both the layout of the IR code and additional information related to its replication mechanism. You can learn more about each property listed in the model above by reading the official document on the topic.

ToggleMask, the identity bit carrier that helps marking the code as repeated or not, is also implemented through a built-in Phidgets SDK model, and it has the same problem as IRLearnedCode. I implemented this model to replace it in the serializable code:

namespace Coding4Fun.MissionControl.API.Models 
{ 
    public class ToggleMask 
    { 
        public ToggleMask() 
        { 
            
        } 

    public int BitSize { get; set; }         
    public byte[] CodeData { get; set; } 
    } 
}

I also needed an easy way to store all sets at once and carry all associated codes in a single instance retrieved from the storage. Here is the Set class:

namespace Coding4Fun.MissionControl.API.Models 
{     
    public class Set 
    { 
        public Set() 
        { 
            Commands = new List<Command>(); 
        } 
        
    public string Name { get; set; } 
    public bool IsList { get; set; } 
    public List<Command> Commands { get; set; } 
    } 
}

Notice that there is an IsList flag that allows me to specify how to display this specific list on the connecting device. This adds some level of flexibility for situations where the user wants to build a virtual remote for closely-related keys, such as digits. With that in mind, displaying those as a list might be inconvenient, wasting visual space on the client. But if the flag is set to false, the list can be displayed as a pad.

Also, when the server performs the data exchange, it provides a single “envelope” that allows the connecting device to easily understand what the server is trying to do:

namespace Coding4Fun.MissionControl.API.Models 
{     
    public class ServerResponse     
    {     
    public string Identifier { get; set; }     
    public string Marker { get; set; }     
    public string Content { get; set; }     
    } 
}

The Identifier property carries the server IP address. That way, when a device receives a response, it is able to either accept it, because it knows that a response is requested from a target location, or discard it because the user is no longer using the specific server.

Marker carries the command type of the sent command, therefore giving the Windows Phone application a hint as to what to do with the data. The server can send the following commands:

• SET_LIST – returns the list of sets that are currently available on the server.
• SET_COMMANDS:SET_NAME:IS_LIST – returns the list of commands that are associated with a given set that is currently stored on the server.
• NOTIFICATION – send a simple notification to the client; no further action is required.

Last but not least, Content is used to push the necessary data that is associated with the given Marker. It can be either a JSON-based string that lists the sets or commands, or a plain-text message that is used as an alert for the end-user.

Server Architecture

The server is the only component of this entire system that does all the heavy lifting. It learns commands, stores them and then generates new IR signal requests, as controlled from any of the connected clients. Let’s take a closer look at what happens behind the scenes—to start, I am going to document the network infrastructure.

The Network Layer

In order to be a reliable system, the server needs to be always ready to accept an incoming connection. For that purpose, it is possible to use the TcpListener class—an “always on” receiver that can handle incoming TCP connections. I integrated it in my CoreStarter class that is used to start the listener when the application is launched:

namespace Coding4Fun.MissionControl.API 
{ 
    public class CoreStarter 
    { 
        static TcpListener listener; 
        
        public static void LaunchSocket()     
        {     
            Console.WriteLine("Starting socket server on port {0}...", Constants.DEFAULT_PORT); 
            listener = new TcpListener(NetworkHelper.GetLocalIPAddress(), Constants.DEFAULT_PORT); 
            listener.Start(); 
            
            for (int i = 0; i < Constants.MAX_CONCURRENT_CLIENTS; i++) 
            {     
                Thread socketThread = new Thread(new ThreadStart(ListenForData));     
                socketThread.Start(); 
            } 
        } 
        
        private static void ListenForData() 
        { 
            Console.WriteLine("Listener thread started."); 

            while (true) 
            { 
                Socket acceptedSocket = listener.AcceptSocket(); 
                using (MemoryStream coreStream = new MemoryStream()) 
                {     
                    try 
                    { 
                        Console.WriteLine("Incoming connection: {0}", acceptedSocket.RemoteEndPoint); 
                        
                        using (Stream sourceStream = new NetworkStream(acceptedSocket)) 
                        {     
                            sourceStream.ReadTimeout = Constants.SOCKET_READ_TIMEOUT; 
                            
                            byte[] buffer = new byte[Constants.DEFAULT_BUFFER_SIZE]; 
                            int i; 
                
                            while ((i = sourceStream.Read(buffer, 0, buffer.Length)) != 0) 
                            { 
                                coreStream.Write(buffer, 0, i); 
                            } 
                        } 
                    } 
                    catch 
                    { 
                        string data = Encoding.ASCII.GetString(coreStream.ToArray()); 
        
                        CommandHelper.InterpretCommand(data, acceptedSocket.RemoteEndPoint.ToString()); 
                    } 
                } 
            } 
        } 
    } 
}

When LaunchSocket is called, the listener is activated on the current machine. As I mentioned above, the port number can be arbitrarily assigned, but has to be consistent between connecting apps in order for the TCP links to be established. Because I expect that more than one device will be connecting to the service at a time, the listener is set as active across a constant number of threads.

NOTE: By default, a there is a maximum limit of 5 simultaneous clients. Although this number can be adjusted, be aware of the requirements of each environment in which a limited number of potential devices can connect. Even though the performance footprint of each thread is minimal, it can have a negative effect if used in unnecessarily large instances.

ListenForData is used to read the incoming stream. When an inbound connection is accepted, the data is read with the help of a fixed content buffer. Then a read timeout is specified to prevent situations where the stream was completely read but the application still waits to pull non-existent data. Once the timeout milestone is hit, an exception is thrown, which marks the end of the stream—at this point, the plain text data that was received (remember that both the server and client exchange text data only) is passed to the command interpreter—CommandHelper, with a reference to the source of the command.

The commands from the device are passed as serialized key-value pairs (KeyValuePair<T, T>), the key being the command with any possible suffixes, and the value being the contents of the command itself that helps the server identify the specific item in the local storage.

InterpretCommand,in this case, does three things sequentially:

1. Deserialize the incoming string and create a KeyValuePair<string,string> instance.
2. Process the command and check whether it is recognizable.
3. Send a response to the client, if deemed necessary by the command type.

The serialization and deserialization is done via JSON.NET. You can install this package in your console managed Win32 project and the Windows Phone application project via NuGet:

The deserialization step is as simple as one line of C# code:

KeyValuePair<string, string> result = JsonConvert.DeserializeObject<KeyValuePair<string, string>>(rawCommand.Remove(0, rawCommand.IndexOf('{')));

The string is sanitized to ensure that only JSON content is being passed to the serializer.

Because of a relatively limited command set, I can put together the entire interpretation stack like this:

// Get the initial list of sets on the target server
if (result.Key == Constants.COMMAND_INIT)
{
    SendSets(sourceLocation);
}
// Create a new set on the target server
else if (result.Key.Contains(Constants.COMMAND_CREATE_SET))
{
    CreateSet(result, sourceLocation);
    SendSets(sourceLocation);
}
// Get the commands that are associated with a given set.
else if (result.Key == Constants.COMMAND_GET_COMMANDS)
{
    SendCommands(result.Value, sourceLocation);
}
// The client requested the server to learn a new command.
else if (result.Key.Contains(Constants.COMMAND_LEARN_COMMAND))
{
    LearnCommand(result, sourceLocation);
}
// The client requested one of the commands to be executed on the 
// target server.
else if (result.Key.Contains(Constants.COMMAND_EXECUTE))
{
    ExecuteCommand(result);
}
// The client has requested a set to be deleted from the target server.
else if (result.Key == Constants.COMMAND_DELETE_SET)
{
    DeleteSet(result.Value);
    SendSets(sourceLocation);
}
// The client has requested a set to be deleted from the target server.
else if (result.Key.Contains(Constants.COMMAND_DELETE_COMMAND))
{
    DeleteCommand(result);
    SendCommands(result.Key.Split(new char[] { ':' })[1], sourceLocation);
}

All commands are constants, declared in the local helper class:

public const string COMMAND_INIT = "INIT"; 

public const string COMMAND_CREATE_SET = "CREATE_SET"; 

public const string COMMAND_GET_COMMANDS = "GET_COMMANDS"; 

public const string COMMAND_LEARN_COMMAND = "LEARN_COMMAND"; 

public const string COMMAND_EXECUTE = "EXECUTE"; 

public const string COMMAND_DELETE_SET = "DELETE_SET";
public const string COMMAND_DELETE_COMMAND = "DELETE_COMMAND";

Notice that these are not the commands that the server sends back, but rather the commands it receives from connecting Windows Phone devices.

Let’s now take a look at the breakdown for each command.

SendSets:

/// <summary> 
/// Send the list of sets to the client that requested those. 
/// </summary> 
/// <param name="sourceLocation">The location of the requesting client.</param> 
private static void SendSets(string sourceLocation) 
{ 
    Console.WriteLine("Received an initial set query from {0}", sourceLocation);     
    ServerResponse response = new ServerResponse(); 
    response.Marker = "SET_LIST"; 
    response.Content = JsonConvert.SerializeObject(StorageHelper.GetRawSetNames()); 
    response.Identifier = NetworkHelper.GetLocalIPAddress().ToString(); 
    NetworkHelper.SendData(sourceLocation, JsonConvert.SerializeObject(response)); 
    Console.WriteLine("Sent the set list to {0}", sourceLocation);     
}

When this command is received, the server does not have to do much processing. It is only invoked when the client establishes the initiating link and needs to know what possible sets it can get from the target machine. The request is logged in the console and a server response is prepared that contains a serialized list of set names, which is later serialized as well and sent back to the source machine location.

StorageHelper and NetworkHelper will be documented later in this article.

CreateSet:

/// <summary> 
/// Create a new set and store it on the local server. 
/// </summary> 
/// <param name="result">The original deserialized command.</param> 
/// <param name="sourceLocation">The location of the requesting client.</param> 
private static void CreateSet(KeyValuePair<string,string> result, string sourceLocation) 
{ 
    bool isSuccessful = false; 
    string[] data = result.Key.Split(new char[] { ':' }); 
    
    Console.WriteLine("There is an attempt to create the {0} set from {1}.", result.Value, sourceLocation); 
    
    if (data[1].ToLower() == "list") 
        isSuccessful = StorageHelper.AddSet(result.Value); 
    else 
        isSuccessful = StorageHelper.AddSet(result.Value, false); 
    
    if (isSuccessful) 
        Console.WriteLine("The {0} set was successfully created.", result.Value); 
    else 
        Console.WriteLine("Something happened and the {0} set was not created.", result.Value);     
}

When a mobile device attempts to create a new set on the server, it sends a command in the following format:

CREATE_SET:list/pad, SET_NAME

CreateSet will get the type of the set that was created, will check whether a set with the same name already exists and will either create it or ignore the command altogether. No notification is sent to the connecting device, but either the failure or the success of the command is registered in the local console.

SendCommands:

/// <summary>
/// Send a list of commands that are associated with the pushed set.
/// </summary>
/// <param name="setName">The original deserialized command.</param>
/// <param name="sourceLocation">The location of the requesting client.</param>
private static void SendCommands(string setName, string sourceLocation)
{
    Console.WriteLine("There was a request to get the commands for the {0} set from {1}.", setName, sourceLocation);
    
    bool isList = StorageHelper.IsSetAList(setName);
    
    ServerResponse response = new ServerResponse();
    response.Marker = string.Format("SET_COMMANDS:{0}:{1}", setName, isList);
    response.Identifier = NetworkHelper.GetLocalIPAddress().ToString();
    response.Content = JsonConvert.SerializeObject(StorageHelper.GetRawCommandNames(setName));
    
    NetworkHelper.SendData(sourceLocation, JsonConvert.SerializeObject(response));
    
    Console.WriteLine("Command list for the {0} set were sent to {1}.", setName, sourceLocation);
}

Commands are sent in the same manner as sets—once the set is recognized, the names of the associated commands are retrieved and serialized inside a ServerResponse instance and then pushed back to the requesting device.

LearnCommand:

/// <summary> 
/// Learn a new command and store it on the target server. 
/// </summary> 
/// <param name="result">The original deserialized command.</param> 
/// <param name="sourceLocation">The location of the requesting client.</param> 
private static void LearnCommand(KeyValuePair<string,string> result, string sourceLocation) 
{     
    Console.WriteLine("[!] Server in COMMAND LEARNING MODE! Point the remote towards the sensor and send a command."); 
    
    string[] data = result.Key.Split(new char[] { ':' });     
    var set = StorageHelper.GetSingleSet(StorageHelper.GetSets(), data[1]); 
    
    if (set != null)     
    {     
        if ((from c in set.Commands where c.Name == result.Value select c).FirstOrDefault() != null) 
        {     
            Console.WriteLine("Cannot learn command {0} for the following set: {1}. Command already exists.", data[1], result.Value); 
            
            ServerResponse response = new ServerResponse();     
            response.Marker = "NOTIFICATION";     
            response.Identifier = NetworkHelper.GetLocalIPAddress().ToString(); 
            response.Content = "We could not save the following command - " + result.Value + ". It already exists in the set."; 
            
            NetworkHelper.SendData(sourceLocation, JsonConvert.SerializeObject(response));     
        } 
        else 
        { 
            if (sensor == null) 
                sensor = new IR(); 
            
            sensor.open(-1); 

            sensor.waitForAttachment(); 
    
            sensor.Learn += (sender, args) => 
            { 
                Console.WriteLine("[!] Server learned the command and is no longer in COMMAND LEARNING MODE."); 
                IRLearnedCode code = args.LearnedCode; 
                code.CodeInfo.MinRepeat = 5; 
            
                Command command = new Command(); 
                command.Name = result.Value; 
                command.Code = IRCodeWorker.GetSerializableIRCode(code); 
                
                StorageHelper.AddCommand(command, set.Name); 
                
                ServerResponse response = new ServerResponse(); 
                response.Marker = "NOTIFICATION"; 
                response.Identifier = NetworkHelper.GetLocalIPAddress().ToString(); 
                response.Content = "The following command has been stored: " + result.Value; 
                
                NetworkHelper.SendData(sourceLocation, JsonConvert.SerializeObject(response)); 
            }; 
        } 
    } 
}

Once a request was received that the server needs to learn a new command, an initial verification is done to make sure that the requested command name and set are not already taken. If neither the command nor the set exist, both will be created.

After the basic setup is complete, the IR sensor is activated and will be waiting for the command to be learned. The way it works is quite simple – the sensor will remain in learning mode until the point where it recognizes a command without error, being 100% sure that it can be reproduced internally. You will need to point your remote towards the sensor and hold the button you want captured for one or two seconds in order for the command to be learned.

NOTE: To ensure that a proper transmission is done, I manually set the minimal repeat value to 5. This is the number of times the sensor will fire the same code towards the target. That is the optimal value for a target device to receive the code if the remote is pointed directly at it without necessarily triggering the same command twice or more.

After the command is learned, the code is processed and transformed into a serializable instance. The connecting client is then notified about whether the command was learned.

ExecuteCommand:

/// <summary> 
/// Execute one of the commands currently stored on the local server. 
/// </summary> 
/// <param name="result">The original deserialized command.</param> 
private static void ExecuteCommand(KeyValuePair<string,string> result) 
{ 
    string[] data = result.Key.Split(new char[] { ':' }); 

    var set = StorageHelper.GetSingleSet(StorageHelper.GetSets(), data[1]); 
    
    if (set != null) 
    {     
        var command = StorageHelper.GetSingleCommand(StorageHelper.GetCommands(set.Name), result.Value); 

        IRLearnedCode code = IRCodeWorker.GetLearnedCode(command.Code); 
        
        if (sensor == null) 
            sensor = new IR(); 

        sensor.open(-1); 
        sensor.waitForAttachment(); 
        sensor.transmit(code.Code, code.CodeInfo); 
        sensor.close(); 
    } 
}

Command execution relies on the hardware sensor. The phone sends a command execution request in the following format:

EXECUTE:SET_NAME, COMMAND_NAME

Once the command is parsed out and found in the local storage, the IR code is transformed back to a model that is recognizable by the Phidgets SDK and transmitted towards the location where the sensor is pointed at the time of the execution.

DeleteSet:

/// <summary> 
/// Delete a single set and all the associated commands 
/// </summary> 
/// <param name="target">The name of the set.</param> 
private static void DeleteSet(string target) 
{ 
    var sets = StorageHelper.GetSets(); 
    var targetSet = StorageHelper.GetSingleSet(sets, target); 
    
    if (targetSet != null) 
    { 
        StorageHelper.RemoveSet(sets, targetSet); 
    } 
}

When deleting a set, only the name of the set should be specified. The user will get a warning on the client side that requires a confirmation of the deletion. The server will blindly execute the command.

DeleteCommand:

private static void DeleteCommand(KeyValuePair<string, string> result)
{
    var sets = StorageHelper.GetSets();
    string setName = result.Key.Split(new char[] {':'})[1];
    var targetSet = StorageHelper.GetSingleSet(sets, setName);
    var command = (from c in targetSet.Commands where c.Name == result.Value select c).FirstOrDefault();
    
    if (command != null)
    {
        targetSet.Commands.Remove(command);
        StorageHelper.SerializeSets(sets);
    }
}

Not only can the user remove entire sets, but he can also target specific commands from a given set. Once a DELETE_COMMAND directive is recognized, the set name is parsed out from the original string, that follows the DELETE_COMMAND:SET_NAME, COMMAND_NAME format, and a simple LINQ query extracts the command instance, removes it and stores the set content on the local hard drive.

Notice that for some commands, particularly for set creation, deletion and command deletion, the server will return a list of the remaining items. The contents will be automatically updated on the devices, which will be waiting for that response. This measure was deliberately introduced to minimize the chances of a user triggering a command that was already deleted or trying to query a previously removed set.

Transforming Codes

You might have noticed that I am using IRCodeWorker.GetSerializableCodeType to transform a Phidgets SDK native IR code model into a serializable one. This is a helper function that performs a field copy of the existing object. Because of the differences in the model structure, it has to be done manually:

public static SerializableIRCode GetSerializableIRCode(IRLearnedCode code) 
{ 
    SerializableIRCode sCode = new SerializableIRCode();     
    sCode.BitSize = code.Code.BitCount;     
    sCode.Encoding = code.CodeInfo.Encoding;     
    sCode.CarrierFrequency = code.CodeInfo.CarrierFrequency;     
    sCode.CodeData = code.Code.Data;     
    sCode.DutyCycle = code.CodeInfo.DutyCycle;     
    sCode.Gap = code.CodeInfo.Gap;     
    sCode.Header = code.CodeInfo.Header;     
    sCode.MinRepeat = 5;     
    sCode.One = code.CodeInfo.One;     
    sCode.Repeat = code.CodeInfo.Repeat;     
    sCode.Trail = code.CodeInfo.Trail;     
    sCode.Zero = code.CodeInfo.Zero;     
    sCode.Mask = new ToggleMask()     
    {         
        BitSize = code.CodeInfo.ToggleMask.BitCount,         
        CodeData = code.CodeInfo.ToggleMask.Data         
    }; 
    
    return sCode;     
}

The reverse process is easier because I can pass each of the existing properties to the IRCodeInfo constructor. The only difference is the fact that I need to use Reflection to create an instance of IRLearnedCode because there is no public constructor defined and a dynamic object has to be created:

internal static IRLearnedCode GetLearnedCode(SerializableIRCode serializableIRCode) 
{ 
    IRCode code = new IRCode(serializableIRCode.CodeData, serializableIRCode.BitSize);     
    IRCodeInfo info = new IRCodeInfo(serializableIRCode.Encoding, serializableIRCode.BitSize, serializableIRCode.Header,     
    serializableIRCode.Zero, serializableIRCode.One, serializableIRCode.Trail, serializableIRCode.Gap, serializableIRCode.Repeat, 
serializableIRCode.MinRepeat, serializableIRCode.Mask.CodeData, IRCodeInfo.IRCodeLength.Constant,
serializableIRCode.CarrierFrequency, serializableIRCode.DutyCycle); 
    
    object[] parameters = new object[] { code, info }; 
    
    BindingFlags flags = BindingFlags.NonPublic | BindingFlags.Instance; 
    object instantType = Activator.CreateInstance(typeof(IRLearnedCode), flags, null, parameters, null); 

    return (IRLearnedCode)instantType; 
}

Command and Set Management

Looking back at the code that I put together for the command interpreter, there is one class that does all local content manipulation—StorageHelper. This is a simple class that performs LINQ queries on set as well as command collections, and makes sure that all the changes are preserved in the sets.xml file in the application folder that is used as the only storage place for all the content that is being manipulated by the server.

namespace Coding4Fun.MissionControl.API.Helpers 
{ 
    public class StorageHelper 
    { 
        
        /// <summary> 
        /// Lists all available sets that are currently stored on the server.         
        /// </summary> 
        /// <returns>List of sets on the machine.</returns>         
        internal static List<Set> GetSets()         
        {             
            List<Set> sets = null; 
            
            string rawContent = GetRawSets();             
            sets = JsonConvert.DeserializeObject<List<Set>>(rawContent); 
            
            return sets;             
        } 
        
        /// <summary>         
        /// Returns the list of commands that are associated with the given set.         
        /// </summary>         
        /// <param name="setName">The name of the target set.</param>         
        /// <returns>List of commands associated with the given set.</returns>         
        internal static List<Command> GetCommands(string setName)         
        {             
            List<Command> commandList = null; 
            
            var sets = GetSets(); 
            
            Set singleSet = null;             
            if (sets != null)             
                singleSet = (from c in sets where c.Name == setName select c).FirstOrDefault(); 
            
            if (singleSet != null)         
            {         
                commandList = singleSet.Commands;     
            } 
            
            return commandList; 
        } 
        
        /// <summary>     
        /// Gets the list of names for the commands in the requested set. 
        /// </summary> 
        /// <param name="setName">The name of the target set.</param> 
        /// <returns>List of commands associated with the given set.</returns> 
        internal static List<string> GetRawCommandNames(string setName) 
        { 
            List<Command> commandList = GetCommands(setName); 
            
            List<string> stringSet = null; 
            
            if (commandList != null) 
            {     
                stringSet = commandList.Select(x => x.Name).ToList();     
            } 
            
            return stringSet;     
        } 
        
        /// <summary> 
        /// Get the list of names for all sets on the local server. 
        /// </summary> 
        /// <returns>List of sets on the machine.</returns> 
        internal static List<string> GetRawSetNames() 
        {     
            List<Set> sets = GetSets(); 
            
            List<string> stringSet = null; 
    
            if (sets != null) 
            {     
                stringSet = sets.Select(x => x.Name).ToList();     
            } 
            
            return stringSet; 
        } 
        
        /// <summary> 
        /// Get the raw string contents of sets.xml. Should only be used in the 
        /// context of this class. 
        /// </summary> 
        /// <returns>JSON string representing stored sets and commands.</returns> 
        internal static string GetRawSets() 
        { 
            string sets = string.Empty; 
            
            if (File.Exists("sets")) 
            { 
                using (StreamReader reader = new StreamReader(File.OpenRead("sets"))) 
                { 
                    sets = reader.ReadToEnd(); 
                } 
            } 
            else 
            { 
                FileStream stream = File.Create("sets.xml"); 
                
                stream.Close();     
            } 
            
            return sets; 
        } 
        
        /// <summary> 
        /// Check whether a set is marked with a IsList flag. 
        /// </summary> 
        /// <param name="setName">The name of the target set.</param> 
        /// <returns>TRUE - set is a list. FALSE - set is not a list.</returns> 
        internal static bool IsSetAList(string setName) 
        { 
            bool isList = true; 
            var sets = GetSets(); 
            Set set = null; 

            if (sets != null) 
                set = (from c in sets where c.Name == setName select c).FirstOrDefault(); 
            
            if (set != null) 
                isList = set.IsList; 
            
            return isList;     
        } 
        
        /// <summary> 
        /// Serialize the set collection to sets.xml 
        /// </summary> 
        /// <param name="sets">Collection to be serialized.</param> 
        /// <returns>true if sets are serialized.</returns> 
        private static bool SerializeSets(List<Set> sets) 
        { 
            try 
            { 
                using (StreamWriter writer = new StreamWriter("sets.xml", false)) 
                {     
                    string data = JsonConvert.SerializeObject(sets); 
            
                    writer.Write(data); 
                } 
                
                return true; 
            } 
            catch 
            {     
                return false;     
            } 
        } 
        
        /// <summary> 
        /// Add a new set to the existing global set collection. 
        /// </summary> 
        /// <param name="name">Set name.</param> 
        /// <returns>true if successfully added set.</returns> 
        internal static bool AddSet(string name, bool isList = true) 
        { 
            var sets = GetSets(); 

            if (sets == null) 
                sets = new List<Set>(); 
            
            var singleSet = GetSingleSet(sets, name); 

            if (singleSet == null) 
                sets.Add(new Set { Name = name, IsList = isList }); 
            
            if (SerializeSets(sets)) 
                return true; 
            else 
                return false; 
        } 
        
        /// <summary> 
        /// Retrieves a single set from a collection that has a specific name. 
        /// </summary> 
        /// <param name="sets">The source collection from which to extract the set.</param> 
        /// <param name="name">The name of the set to get.</param> 
        /// <returns>An instance of the found set, if any.</returns> 
        internal static Set GetSingleSet(List<Set> sets, string name) 
        { 
            if (sets != null) 
                return (from c in sets where c.Name == name select c).FirstOrDefault(); 
            else 
                return null; 
        } 
        
        /// <summary> 
        /// Add a IR command to an existing set. If the set is not found, it will be created. 
        /// </summary> 
        /// <param name="command">The command instance to be added.</param> 
        /// <param name="targetSet">The name of the target set.</param> 
        /// <returns>true if the command was successfully added.</returns> 
        internal static bool AddCommand(Command command, string targetSet) 
        { 
            var sets = GetSets(); 
            
            if (sets == null) 
                sets = new List<Set>(); 
            
            var singleSet = GetSingleSet(sets, targetSet); 
            
            if (singleSet == null) 
                singleSet = new Set { Name = targetSet }; 
            
            var singleCommand = (from c in singleSet.Commands where c.Name == command.Name select c).FirstOrDefault(); 
            
            if (singleCommand == null) 
            { 
                singleSet.Commands.Add(command); 
                
                if (SerializeSets(sets)) 
                    return true; 
                else 
                    return false; 
            } 
            else 
                return false; 
        } 
        
        /// <summary> 
        /// Retrieve a single command instance from one of the sets on the local server. 
        /// </summary> 
        /// <param name="commands">Original list of commands.</param> 
        /// <param name="name">Name of the command to be retrieved.</param> 
        /// <returns>An instance of the command, if found. NULL if not.</returns> 
        internal static Command GetSingleCommand(List<Command> commands, string name) 
        { 
            if (commands != null) 
                return (from c in commands where c.Name == name select c).FirstOrDefault(); 
            else 
                return null; 
        } 
        
        /// <summary> 
        /// Remove a set from a local machine. 
        /// </summary> 
        /// <param name="sets">Original list of sets.</param> 
        /// <param name="targetSet">Name of the set to remove.</param> 
        internal static void RemoveSet(List<Set> sets, Set targetSet) 
        { 
            sets.Remove(targetSet); 
            
            SerializeSets(sets); 
        } 
    } 
}

Sending Data Back to the Client

SendData in the NetworkHelper class handles all outbound connections. Here is its structure:

/// <summary> 
/// Send data to the target network machine. 
/// </summary> 
/// <param name="destination">The target machine IP.</param> 
/// <param name="data">Data to be sent, in string format.</param> 
/// <param name="sanitizeIp">Determines whether to remove the port from the given IP string.</param> 
public static void SendData(string destination, string data, bool sanitizeIp = true) 
{ 
    using (Socket client = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp)) 
    {     
        string completeIp = string.Empty; 
        
        if (sanitizeIp)     
            completeIp = destination.Remove(destination.IndexOf(":"), destination.Length - destination.IndexOf(":")); 
        
        client.Connect(completeIp, 6169); 
        client.Send(Encoding.UTF8.GetBytes(data));     
    }     
}

A new stream socket is created in order to connect to the target machine over the TCP pipe. If IP sanitization is enabled, the port is stripped from the address in order to pass a valid IP. A Socket instance cannot directly handle IPs of the format:

255.255.255.0:PORT_NUMBER

Later, in a synchronous manner, a connection is established and the data is sent.

At this point, you can see that the barebones service offers a flexible way to manage content. It can be accessed by any application type as long as the server can be accessed and the application can send commands in the pre-defined format and the content requested is actually located on the target server. This allows for high levels of extensibility and interoperability, as the server usage is not limited to a single platform. If I decide to create a Windows Store application that would allow me to control my TV, I simply need to add socket connection layer that will send plain strings to the machine where the IR sensor is connected.

Similarly, if some functionality needs to be added, it is possible to do so without ever touching the client applications. A modification in the endpoint will be reflected with no direct effect on all connection applications as long as all handled returned and requested values are preserved. The only additional requirement is that if the client applications want to take advantage of newly introduced capabilities, they need to have an updated command transmission layer for the new command types.

In Program.cs, I simply need to start the server through the CoreStarter class:

namespace Coding4Fun.MissionControl.API 
{ 
    class Program     
    {         
        static void Main(string[] args)         
        {             
            Console.WriteLine("Coding4Fun MissionControl Server");             
            CoreStarter.LaunchSocket();             
        }         
    }     
}

Mobile client overview

The mobile client does not have the capability to send commands directly to the IR sensor. Instead, it connects to a remote machine that has the IR sensor plugged in and attempts to invoke a command from the list returned by the service. A single mobile client can support control over multiple servers.

NOTE: Make sure that at the time of working with the Windows Phone client, the server is actually running on your local machine. To make it easier to test, also open port 6169 for incoming connections in Windows Firewall.

When building a Windows Phone application, make sure you have the proper version of the SDK installed, as well as a SLAT-compatible machine if you plan on testing the application in the emulator.

Networking Infrastructure

The Windows Phone application also relies on a network infrastructure somewhat similar to that of the server. There is a TCP listener that is created when the application is started:

// Code to execute when the application is launching (eg, from Start) 
// This code will not execute when the application is reactivated 
private void Application_Launching(object sender, LaunchingEventArgs e) 
{ 
    ServiceSerializer.DeserializeServices(); 
    
    listener.OnClientConnected += listener_OnClientConnected; 
    listener.Start(6169); 
}

Here, listener is an instance of TcpSocketListener—a custom class designed to handle incoming network connections:

namespace Coding4Fun.MissionControl.WP.Network 
{ 
    public class TcpSocketListener : SocketConnectorBase     
    {     
        StreamSocketListener coreSocket; 
        
        public async void Start(int port)     
        {     
            coreSocket = new StreamSocketListener();         
            coreSocket.ConnectionReceived += coreSocket_ConnectionReceived; 
            
            try     
            {         
                await coreSocket.BindServiceNameAsync(port.ToString());         
            }     
            catch (Exception ex) 
            {     
                Debug.WriteLine(ex.Message); 
                
                coreSocket.Dispose();     
                coreSocket = null; 
                OnConnectionCompleted(new ConnectionEventArgs { IsSuccessful = false, DeviceID = string.Empty }); 
            } 
        } 
        
        async void coreSocket_ConnectionReceived(StreamSocketListener sender, StreamSocketListenerConnectionReceivedEventArgs args) 
        { 
            Debug.WriteLine("Connection received!"); 
            
            DataReader reader = new DataReader(args.Socket.InputStream); 
            
            try 
            { 
                while (true) 
                { 
                    StringBuilder builder = new StringBuilder(); 
        
                    uint actualLength = 1; 

                    while (actualLength > 0) 
                    {     
                        actualLength = await reader.LoadAsync(256); 
                        builder.Append(reader.ReadString(actualLength)); 
                    } 
                    
                    OnConnectionCompleted(new ConnectionEventArgs 
                    { 
                        Socket = args.Socket, 
                        IsSuccessful = true, 
                        DeviceID = args.Socket.Information.RemoteHostName.DisplayName, 
                        Token = builder.ToString() 
                    }); 
                    break; 
                } 
            } 
            catch (Exception exception) 
            { 
                Debug.WriteLine(exception.Message); 
                
                OnConnectionCompleted(new ConnectionEventArgs { IsSuccessful = false }); 
            } 
        } 
    } 
}

A StreamSocketListener is used for the connection core. When a connection is received, a continuous loop reads the entire contents of the incoming stream. OnConnectionCompleted is declared in the base class—SocketConnectorBase.

namespace Coding4Fun.MissionControl.WP.Network 
{ 
    public class SocketConnectorBase 
    { 
        public event EventHandler<ConnectionEventArgs> OnClientConnected; 
        public virtual void OnConnectionCompleted(ConnectionEventArgs connectionArgs) 
        { 
            if (OnClientConnected != null) 
            { 
                OnClientConnected(this, connectionArgs); 
            } 
        } 
        
        public event EventHandler<bool> OnSendCompletedEvent; 
        public virtual void OnSendCompleted(bool succeeded) 
        { 
            if (OnSendCompletedEvent != null) 
            { 
                OnSendCompletedEvent(this, succeeded); 
            } 
        } 
    } 
    
    public class ConnectionEventArgs : EventArgs 
    { 
        public StreamSocket Socket { get; set; }     
        public string DeviceID { get; set; }     
        public string Token { get; set; }     
        public bool IsSuccessful { get; set; }     
    } 
}

ConnectionEventArgs here is used to identify the content that is passed to the client. DeviceID gives access to the source IP, IsSuccessful tells the developer whether the established connection is active and the Token carries the raw string if any was received.

Sending data is simplified to the maximum with the help of the SocketClient class, which relies on a StreamSocket instance that handles outbound connections and writing to the output stream:

namespace Coding4Fun.MissionControl.WP.Network 
{ 
    public class SocketClient : SocketConnectorBase 
    {     
        StreamSocket _socket; 
        
        public SocketClient() 
        {     
            _socket = new StreamSocket();     
        } 
        
        public SocketClient(StreamSocket socket) 
        {     
            _socket = socket;     
        } 
        
        public async void Connect(string hostName, int portNumber) 
        { 
            try 
            { 
                await _socket.ConnectAsync(new HostName(hostName), portNumber.ToString(), SocketProtectionLevel.PlainSocket); 
            
                OnConnectionCompleted(new ConnectionEventArgs { IsSuccessful = true }); 
            } 
            catch (Exception ex) 
            {     
                Debug.WriteLine(ex.Message); 
                
                OnConnectionCompleted(new ConnectionEventArgs { IsSuccessful = false });     
            } 
        } 
        
        public async void Send(string dataToSend) 
        { 
            try 
            {     
                using (DataWriter writer = new DataWriter(_socket.OutputStream)) 
                { 
                    // Write the length of the binary data that is being 
                    // sent to the client. 
                    writer.WriteUInt32((UInt32)dataToSend.Length); 
                    
                    writer.WriteString(dataToSend); 
        
                    // Send the actual data. 
                    await writer.StoreAsync(); 
                    
                    writer.DetachStream(); 
                    
                    OnSendCompleted(true); 
                } 
            } 
            catch 
            { 
                _socket.Dispose();     
                _socket = null;     
                OnSendCompleted(false);     
            }     
        }     
    }     
}

As with the listener class, SocketClient supports OnConnectionCompleted to notify the application that the connection attempt completed.

Back in App.xaml.cs, the data from the incoming connection captured by the TcpSocketListener instance is passed to the ResponseHelper class:

void listener_OnClientConnected(object sender, ConnectionEventArgs e) 
{ 
    ResponseHelper.HandleIncomingResponse(e.Token); 
}

This class reads the possible three commands sent by the server and interprets them, creating internal collections from the raw data if the current server IP matches the one obtained in the ServerResponse (the same model in the desktop application):

using Coding4Fun.MissionControl.WP.Models;
using Coding4Fun.MissionControl.WP.ViewModels;
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Windows;

namespace Coding4Fun.MissionControl.WP.Misc
{
        public class ResponseHelper
        {
                public static void HandleIncomingResponse(string rawResponse)
                {
                        if (rawResponse != null)
                        {
                                ServerResponse response = JsonConvert.DeserializeObject<ServerResponse>(rawResponse);
                
                                if (response.Marker == Constants.COMMAND_SERVER_NOTIFICATION)
                                {
                                        Deployment.Current.Dispatcher.BeginInvoke(() =>
                                        {
                                                MessageBox.Show(response.Content, "Server Response", MessageBoxButton.OK);
                                        });
                                }
                                else
                                {
                                        if (CommonViewModel.Instance.IsWaiting)
                                        {
                                                if (response.Identifier == CommonViewModel.Instance.CurrentServer.Location)
                                                {
                                                        // returns the list of sets that are associated with the current server.
                                                        if (response.Marker == Constants.COMMAND_SERVER_SET_LIST)
                                                        {
                                
                                                                List<string> items = JsonConvert.DeserializeObject<List<string>>(response.Content);
                                
                                                                if (items != null)
                                                                {
                                                                        List<Group<string>> groupedItems = Group<string>.CreateGroups(items,
                                                                        CultureInfo.CurrentCulture, (string s) => { return s[0].ToString(); }, true);
                                                                        SetsPageViewModel.Instance.Sets = groupedItems;
                                                                }
                                                                else
                                                                {
                                                                        SetsPageViewModel.Instance.Sets = new List<Group<string>>();
                                                                }
                                
                                                                Deployment.Current.Dispatcher.BeginInvoke(() =>
                                                                    {
                                                                            CommonViewModel.Instance.IsWaiting = false;
                                    
                                                                            if (!App.RootFrame.CurrentSource.ToString().Contains("SetsPage"))
                                                                            {
                                                                                    App.RootFrame.Navigate(new Uri("/Views/SetsPage.xaml", UriKind.Relative));
                                                                            }
                                                                    });
                                
                                                        }
                                                        // returns the list of commands associated with a given set.
                                                        else if (response.Marker.Contains(Constants.COMMAND_SERVER_SET_COMMANDS))
                                                        {
                                                            string[] data = response.Marker.Split(new char[] { ':' });
                                                                if (data[1] == CommonViewModel.Instance.CurrentSet)
                                                                {
                                                                        bool isList = false;
                                                                        bool.TryParse(data[2].ToLower(), out isList);
                                    
                                                                        if (isList)
                                                                        {
                                                                                CommonViewModel.Instance.CurrentSetType = "list";
                                                                        }
                                                                        else
                                                                        {
                                                                                CommonViewModel.Instance.CurrentSetType = "pad";
                                                                        }
                                    
                                                                        CommandsPageViewModel.Instance.Commands = new System.Collections.ObjectModel.ObservableCollection<string>(JsonConvert.DeserializeObject<List<string>>(response.Content));
                                    
                                                                        Deployment.Current.Dispatcher.BeginInvoke(() =>
                                                                            {
                                                                                    CommonViewModel.Instance.IsWaiting = false;
                                                                                    App.RootFrame.Navigate(new Uri("/Views/CommandsPage.xaml", UriKind.Relative));
                                                                            });
                                                                }
                                                        }
                                                }
                                        }
                                }
                        }
                }
        }
}

If the response comes from a server that is different than the one that is currently active, the data is discarded as the user no longer needs it. Also, for specific commands, the mobile application will be on standby, waiting for a response (unless the user decides to cancel the request) – the IsWaiting flag is an application-wide indicator that a pending server action is in the queue.

Same as with the server, the commands in the Windows Phone application are represented through pre-defined constants:

public const string COMMAND_SERVER_SET_LIST = "SET_LIST"; 

public const string COMMAND_SERVER_SET_COMMANDS = "SET_COMMANDS"; 

public const string COMMAND_SERVER_NOTIFICATION = "NOTIFICATION";

Let’s now take a closer look at how it is handled internally to build the visual layer.

Handling the Data

The first thing users will see when the application is launched is the list of registered servers:

This is ServiceListPage.xaml. The list of servers that were added is retrieved from the isolated storage on application startup, with the help of the standard serialization routine implemented in the Coding4Fun Toolkit—specifically, its storage subset (you can get it via NuGet):

The one-liner that initializes the internal server collection is as follows:

MainPageViewModel.Instance.Servers = Serialize.Open<ObservableCollection<Server>>(Constants.SERVERS_FILE);

Here, the SERVERS_FILE constant is equal to servers.xml. It is a good idea to use constants for file names in order to be able to later modify the location through a single change instead of digging through the many source files in a solution to find references to the old location.

The user can define an unlimited number of servers, as long as he can access those. There is no restriction on the location of the server itself—it can work with the desktop in your room just as well as with a PC on the other end of the world (yes, this was tested).

When adding a new server, the user is redirected to AddServicePage.xaml, where he can fill in connection details, as well as the location of an image that would help him identify that specific item in the general list:

Once data entry is complete, it is validated internally to make sure that the server is not already registered with the same name and location. If the validation step passes, the server is added to the list of local access points and the user is returned back to the server selection page:

private void AttemptAddService()
{
        if (!string.IsNullOrWhiteSpace(txtName.Text) && !string.IsNullOrWhiteSpace(txtLocation.Text))
        {
                Server server = new Server
                    {
                            Name = txtName.Text,
                            Location = txtLocation.Text,
                            ImageURL = !string.IsNullOrWhiteSpace(txtAvatar.Text) ? txtAvatar.Text : string.Empty
                    };
        
                if (!CollectionHelper.CheckServerExists(server))
                {
                        MainPageViewModel.Instance.Servers.Add(server);
            
                        Serialize.Save(Constants.SERVERS_FILE, MainPageViewModel.Instance.Servers);
                        NavigationService.GoBack();
                }
                else
                {
                        Alert.Send("The service with this name or location is already registered.");
                }
        }
        else
        {
                Alert.Send("The service needs a name and a location.");
        }
}

When a server selection is made by the user, it is necessary to show SetsPage.xaml. However, it is necessary to also check whether the server is active or not prior to the actual navigation. With the help of internal bindings, I am doing it through a RelayCommand:

public RelayCommand SelectServerCommand { get; private set; }
private async void SelectServer(object server)
{
        CommonViewModel.Instance.IsWaiting = true;
        CommonViewModel.Instance.CurrentServer = (Server)server;
    
        bool result = await CommonViewModel.Instance.CommandClient.SendCommand(CommonViewModel.Instance.CurrentServer.Location, 
        Constants.COMMAND_SERVER_HELLO, string.Empty);
        if (!result)
        {
                Alert.Send(Constants.MESSAGE_SERVER_CONNECT_FAIL);
                CommonViewModel.Instance.CurrentServer = null;
        
                CommonViewModel.Instance.IsWaiting = false;
        }
}

COMMAND_SERVER_HELLO represents the initial handshake command that I mentioned earlier—it requests the list of sets on the target server. To streamline command processing, CommandClient is used and wraps around the SocketClient class, giving me the possibility to call SendCommand with the command metadata without having to explicitly handle socket interactions in my views:

namespace Coding4Fun.MissionControl.WP.Network 
{     
    public class CommandClient     
    {     
        private SocketClient client; 
        
        public Task<bool> SendCommand(string key, string value, Action<bool> onCompleted = null) 
        {     
            var taskCompletionSource = new TaskCompletionSource<bool>(); 
            
            client = new SocketClient();     
            client.OnClientConnected += (s, args) =>     
            {     
                if (args.IsSuccessful)     
                {     
                    string data = JsonConvert.SerializeObject(new KeyValuePair<string, string>(key, value));     
                    client.Send(data);     
                } 
            
                taskCompletionSource.SetResult(args.IsSuccessful); 
                client = null; 
            }; 
            
            client.Connect(Binder.Instance.CurrentService.Location, 6169); 
            return taskCompletionSource.Task;     
        } 
    } 
}

From here on, ResponseHelper is once again involved, grouping all the data alphabetically—remember this call:

// returns the list of sets that are associated with the current server. 
if (response.Marker == Constants.COMMAND_SERVER_SET_LIST) 
{     
    List<string> items = JsonConvert.DeserializeObject<List<string>>(response.Content);     
    if (items != null) 
    {     
        List<Group<string>> groupedItems = Group<string>.CreateGroups(items,     
    CultureInfo.CurrentCulture, (string s) => { return s[0].ToString(); }, true);     
        Binder.Instance.Sets = groupedItems;     
    } 
    else 
    {     
        Binder.Instance.Sets = new List<Group<string>>();     
    } 
}

The grouped collection is later bound to a LongListSelector instance:

For each handshake call to the server, the set collection will be re-initialized, in case the server was updated by another device while the user was not taking any actions.

Adding a set takes the user to AddSetPage.xaml, where the user input is once again validated and the appropriate command sent to the currently selected server:

private async void AttemptAddSet()
{
        if (!string.IsNullOrWhiteSpace(txtName.Text))
        {
                this.Focus();
        
                bool commandSent = await CommonViewModel.Instance.CommandClient.SendCommand(CommonViewModel.Instance.CurrentServer.Location, 
                    string.Format(Constants.COMMAND_CREATE_SET, ((ListPickerItem)lstType.SelectedItem).Content.ToString()), txtName.Text);
                if (!commandSent)
                {
                        Alert.Send(Constants.MESSAGE_SERVER_CONNECT_FAIL);
                }
                else
                {
                        CommonViewModel.Instance.IsWaiting = true;
                        NavigationService.GoBack();
                }
        }
        else
        {
                Alert.Send(Constants.MESSAGE_NO_NAME_FAIL);
        }
}

The end-user is also able to specify whether the new set is a list or a pad. Since the server does not explicitly define the type of a set beyond marking whether it’s a list, it is possible to have an arbitrary type here.

To give you an idea of what it looks like in the current release of MissionControl, here is the pad representation of a set of commands:

It is a convenient way to display buttons for typical actions, such as channel switching through digits. Since we can safely assume many of those will be tapped sequentially, a list would be inconvenient to scroll through.

On the other hand, some remote control commands work well with a list because no sequences are invoked most of the time:

If the pad is not desired, it can easily be swapped with another design and internal template - the appearance is swapped dynamically and is not hard-bound to a string value.

Once a set is selected, a connection attempt is made to the current server in order to check whether there is still a communication channel available with the resource that fetched the initial list of commands. If a connection is established, the server will also return a set of commands that are available in the set at the time of the request.

private async void AttemptLoadCommands()
{
        bool commandSent = await CommonViewModel.Instance.CommandClient.SendCommand(CommonViewModel.Instance.CurrentServer.Location,
            Constants.COMMAND_GET_COMMANDS, CommonViewModel.Instance.CurrentSet);
        if (!commandSent)
        {
                Alert.Send(Constants.MESSAGE_SERVER_CONNECT_FAIL);
                CommonViewModel.Instance.IsWaiting = false;
        }
}

You’ve probably already noticed that both for commands and sets, the initial routine verifies the connection to the server. The server might go dark after the set list is loaded, therefore rendering any attempt to process other commands impossible. To avoid scenarios in which the user is waiting for a response from a server that doesn’t run, the user is notified before being redirected to the subsequent view, if the connection fails. That way unnecessary navigation passes are out of the picture.

If the user selects a command from one of the lists demonstrated above, an EXECUTE directive is issued via the CommandClient class:

private async void lstCommands_SelectionChanged(object sender, SelectionChangedEventArgs e) 
{ 
    if (lstCommands.SelectedItem != null)
    { 
        string selectedItem = lstCommands.SelectedItem.ToString(); 
        
        CommandClient commandClient = new CommandClient(); 
        bool commandSent = await commandClient.SendCommand(string.Format(Constants.COMMAND_EXECUTE, 
        
        Binder.Instance.CurrentSet), selectedItem); 
    
        if (!commandSent) 
        {     
            Alert.Send(Constants.MESSAGE_SERVER_CONNECT_FAIL);     
        } 
        
        lstCommands.SelectedItem = null; 
    } 
}

Once the server receives the command, it will send it to the target without additional notifications being released to the connecting client.

When it comes to learning a new remote control code in LearnCodePage.xaml, the procedure is exactly the same as with any other part of the server communication process — a LEARN_CODE command is sent to the server with the associated set and new command name, and the server will wait for incoming IR input, leaving the connecting device free (no waiting lock is issued):

private async void AttemptLearnCode()
{
        if (!string.IsNullOrWhiteSpace(txtName.Text))
        {
                CommonViewModel.Instance.IsWaiting = true;
                this.Focus();
        
                bool commandSent = await CommonViewModel.Instance.CommandClient.SendCommand(CommonViewModel.Instance.CurrentServer.Location,
                    string.Format(Constants.COMMAND_LEARN_NEW, CommonViewModel.Instance.CurrentSet), txtName.Text);
                if (!commandSent)
                {
                        Alert.Send(Constants.MESSAGE_SERVER_CONNECT_FAIL);
                }
                else
                {
                        Alert.Send(Constants.MESSAGE_COMMAND_LEARN_WAIT);
                        NavigationService.GoBack();
                }
        
                CommonViewModel.Instance.IsWaiting = false;
        }
        else
        {
                Alert.Send(Constants.MESSAGE_NO_NAME_FAIL);
        }
}

Once the server learns a new command — if, and only if, the user still works in the context of the same server — an alert will be displayed, telling the user whether the command was successfully learned.

For convenience purposes, I also implemented a quick launch panel, where frequently-used commands can be placed. Whenever a user wants to add something here, he will tap-and-hold on an existing command in any of the sets that are available for any given server, and select the "add to quick launch" option. Once completed, the stored commands will be available on the main page, even when the user is not directly connected to the server that carries the command:

Because this interaction layer is placed outside the boundaries of a single server or set, I needed to create a special data model to store the quick commands and the related connection information, that would let me call the server even when it is not the currently selected one:

namespace Coding4Fun.MissionControl.WP.Models
{
        public class Favorite
        {
            public string CommandName { get; set; }
            public string ParentSet { get; set; }
            public string ServerLocation { get; set; }
        }
}

Same as with the list of servers, the list of favorites is deserialized on application startup:

MainPageViewModel.Instance.Favorites = Serialize.Open<ObservableCollection<Favorite>>(Constants.FAVORITES_FILE);

Logically, we would also need to have a way to eliminate trailing commands for servers or sets that have been removed, since those can no longer be invoked or might have a different meaning on servers that were added and have the same IP as the previous owner. This is easily done with a simple LINQ expression that is passed to RemoveTrailingFavorites in the CollectionHelper class:

internal static void RemoveTrailingFavorites(Func<Favorite,bool> predicate)
{
        var favorites = MainPageViewModel.Instance.Favorites.Where(predicate).ToList();
    
        if (favorites.Count() > 0)
        {
                foreach (var favorite in favorites)
                {
                        Deployment.Current.Dispatcher.BeginInvoke(() =>
                            {
                                    MainPageViewModel.Instance.Favorites.Remove(favorite);
                            });
                }
        
                Serialize.Save(Constants.FAVORITES_FILE, MainPageViewModel.Instance.Favorites);
        }
}

A typical usage scenario is reflected in the server removal snippet:

public static bool RemoveServer(Server server)
{
        try
        {
                RemoveTrailingFavorites(x=> x.ServerLocation == server.Location);
        
                MainPageViewModel.Instance.Servers.Remove(server);
        
                Serialize.Save(Constants.SERVERS_FILE, MainPageViewModel.Instance.Servers);
        
                return true;
        }
        catch
        {
                return false;
        }
}

Because an ObservableCollection<T> is used for both the list of servers and quick launch commands, the view will be instantly updated to reflect the changes.

Improvements to the project

This specific project relies on a hybrid IR transmitter and receiver, which is not exactly cheap. As a step forward for this project, it can be adapted to use a central microcontroller that acts as a server (e.g. Netduino) and a series of IR emitters (instead of using a composite receiver/emitter) connected to it. Reduced cost for the IR infrastructure is key, as not every single component needs the capability to learn IR commands. You can have a single command capturing endpoint and multiple transmitters. This will also eliminate the need for a desktop client, since the server on the microcontroller can be built to be accessible via a web-browser.

Another important aspect not covered in this article is security. With the current workflow, anyone who has direct access to the server IP is able to do anything he wants with the data handled by the server. I am basing my writing on the assumption that you are testing the application on a secure local network and that the the odds of something like this happening are close to zero. However, for other environments where tampering with a server might be unacceptable, consider implementing a layer of security between the server and the client.

Conclusion

With affordable microcontrollers and sensors, home and office automation can be a nice bonus resulting from little investment. This article covers the implementation of a proof-of-concept server and application that can be easily extended and adapted to a variety of environments and devices.

What do you need

You will need to download and install ASP.NET MVC3 to work on the web frontend and Windows Phone 8 SDK to work on the mobile applications. An Azure Mobile Services account will be necessary, and of course don’t forget to download and install the Azure Mobile Services client libraries. All three components are available at no additional charge.

NOTE: Without the Azure Mobile Services SDK installed on the development machine, the compilation process will fail for the Windows Phone application.

Setting up The Data Store

First we need to establish the general design of the application and organize the workflow. The application will provide two ways to assign the dynamic lockscreen:

• With the help of custom image sets that are provided by the service;
• With the help of self-created image sets, aggregated from images provided by the service but ultimately managed by the end-user.

Let’s talk about the general data model. Every image belongs to a certain category and to keep track of each we need a table with two columns—category ID and category name. We also need another core table containing the image references themselves, with the following columns: image URL, descriptive name, and the category ID to which it belongs. The overall structure looks like this:

Now to the Windows Azure Management Portal and creating a new Mobile Service.

Once created, you need to specify database information, just like you would with a standard SQL Server database:

As the database is being created, you can easily integrate it with SQL Server Management Studio. You will need the server address, which may be obtained in the Azure Management Portal. To login, use the credentials that you set when creating the core database.

Create the two tables mentioned above, with the following column configuration:

Categories

• ID - int
• Name – varchar(100)

Images

• ID – int
• URL – varchar(500)
• Name – varchar(100)
• CategoryID – int

You can create these tables either in the SQL Server Management Studio or through the Azure Management Portal. However, you will need the Management Studio to create the column structure, as the Azure Management Portal does not offer this functionality right now.

By default, the id column will be created automatically. To add the Name column to the Categories table, run this query:

ALTER TABLE c4flockscreen.Categories
ADD Name VARCHAR(100)

To add the missing columns to the Images table, simply execute this query:

ALTER TABLE c4flockscreen.Images
ADD URL VARCHAR(500),
Name VARCHAR(100),
CategoryID INT

Now that the database is ready, we’ll proceed to working on the web layer, which will effectively be the administrative portal for the service.

Creating the Web Portal

There should be a way to easily manage images and constantly expand the collection of possible lockscreen wallpapers. One way to do this is create a basic management portal that can carry basic CRUD operations.

Start by creating an empty project:

If you are not yet aware of the Model-View-Controller (MVC) development pattern, here is a good read explaining the fundamentals.

Create a new controller in the Controllers folder, named HomeController. This will be the only controller created in this project. For now, add an ActionResult-based function that will return the main view:

using System.Web.Mvc;

namespace Coding4Fun.Lockscreen.Web.Controllers
{
    public class HomeController : Controller    
    {    
        public ActionResult MainView()    
        {    
            return View();    
        }
    }
}

Having the controller without the proper views is pointless, so create a new view in Views/Home and name it MainView. For now, do not focus on the visual layout of the page, but rather on the functional aspect of the web frontend. If you run the application now, you will most likely get a 404 response. That is because the associated home view is by default not found. Open App_Start/RouteConfig.cs and make sure that the default view is set to MainView instead of Index.

routes.MapRoute(
name: "Default",
url: "{controller}/{action}/{id}",
defaults: new { controller = "Home", action = "MainView", id = UrlParameter.Optional }
);

The core is created and now if running the web application you will see a basic HTML page:

We now need to handle data from the Azure Mobile Services database. Out-of-the-box, there is no ASP.NET SDK available, but the database can be easily accessed through a REST API. But before that, we need to define the data models for the Categories and Images table. Begin by creating two classes in the Models folder:

Category.cs:

public class Category
{
public int? id { get; set; }
public string Name { get; set; }
}

Image.cs:

public class Image
{
public int? id { get; set; }    
public string URL { get; set; }
public string Name { get; set; }
public int CategoryID { get; set; }
}

Each of the properties is tied to the associated column in the database we created earlier. Notice that the ID values are nullable. This is introduced because the index will by default be automatically assigned. When new instances of Category or Image are created, I will not explicitly set the id property, so keeping it null instead of at a potential default value of 0 will ensure that it is properly set on the backend.

Let’s now create the connectivity engine that will allow us to query the content of the data store. For this purpose, I created a DataStore folder and a DataEngine class inside it. We will need a unique API key for each of our requests, so open the Azure Management Portal and obtain it from there:

In order to keep consistency between projects, and to be able to re-use the same Azure Mobile Services API key and core URL, I created an AuthConstants class in the context of the Coding4Fun.Lockscreen.Core project. It carries three static fields:

public static class AuthConstants
{
    public static string AmsApiKey = "YOUR_KEY_HERE";    
    public const string AmsUrl = "https://c4flockscreen.azure-mobile.net/";
    public const string AmsTableUrl = AmsUrl + "tables/";
}

Back in the ASP.NET project, the query operations are carried with the help of HttpClient initialized in the class constructor, which also includes the key used to authenticate the requests via the X-ZUMO-APPLICATION header:

private HttpClient client;

public DataEngine()
{    
    client = new HttpClient();    
    client.DefaultRequestHeaders.Add("X-ZUMO-APPLICATION", KEY);
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));    
}

This is the basic data harness. I also implemented two core methods in order to get all existing categories:

public IEnumerable<Category> GetAllCategories()
{
    var result = client.GetStringAsync(string.Concat(CORE_URL,"Categories")).Result;
    IEnumerable<Category> categories = JsonConvert.DeserializeObject<IEnumerable<Category>>(result);
    return categories;    
}

And images:

public IEnumerable<Image> GetAllImages()
{
    var result = client.GetStringAsync(string.Concat(CORE_URL, "Images")).Result;
    IEnumerable<Image> images = JsonConvert.DeserializeObject<IEnumerable<Image>>(result);
    return images;    
}

For each of these, a basic request is made with the table name appended to the base URL (represented by the CORE_URL constant). Since JSON.NET is now bundled with ASP.NET, I am able to easily deserialize the returned JSON data array to an IEnumerable<Type>. There is one problem, however, with the GetAllImages approach. It implies that even if I want to use LINQ to query the existing image collection, I have to first download the entire set locally.

Fortunately, the Azure Mobile Services REST API provides an endpoint with filtering, and that’s what I am using in GetCategoryById and GetImagesByCategoryId:

public Category GetCategoryById(int id)
{    
    string composite = string.Concat(CORE_URL, "Categories?$filter=(id%20eq%20", id.ToString(), ")");    
    var result = client.GetStringAsync(composite).Result;
    IEnumerable<Category> categories = JsonConvert.DeserializeObject<IEnumerable<Category>>(result);
    return categories.FirstOrDefault();
}

public IEnumerable<Image> GetImagesByCategoryId(int id)
{    
    string composite = string.Concat(CORE_URL, "Images?$filter=(CategoryID%20eq%20", id.ToString(), ")");    
    var result = client.GetStringAsync(composite).Result;
    IEnumerable<Image> images = JsonConvert.DeserializeObject<IEnumerable<Image>>(result);
    return images();
}

Notice the ?$filter= parameter, in which the conditional is URL encoded and is wrapped in parentheses. For the category query, I am checking the id value, and for the image I’m checking CategoryID.

In the Views/Home folder, create a new view and name it Images. It will be used to list existing images that are associated with one of the selected categories. You also need to adjust the controller code to handle the incoming data:

using Coding4Fun.Lockscreen.Web.DataStore;
using System.Web.Mvc;

namespace Coding4Fun.Lockscreen.Web.Controllers
{    
    public class HomeController : Controller    
    {    
        DataEngine engine;    
        public HomeController()
        {    
            engine = new DataEngine();    
        }
        
        public ActionResult MainView()
        {    
            var categories = engine.GetAllCategories();    
            return View(categories);
        }
        
        public ActionResult Images(int categoryId)
        {    
            var images = engine.GetImagesByCategoryId(categoryId);    
            if (images != null)
            {    
                return View(images);    
            }
            
            return View("MainView");
        }
    }
}

For the main view, I am getting the list of categories and passing them as the bound model. For the Images view, the category ID is passed as an argument that will later enable the engine to return a list of all images that have CategoryID set to that value. In case the returned list is not null, the view is shown. Otherwise, the main view is the terminal point.

In its current state, I’ll be able to use the frontend to list existing categories and images, but not to add, remove, or update items. Adding a category and an image is a matter of modifying an HttpClient request, with the help of HttpRequestMessage. For example, here is how I can add a category through my DataEngine class:

public HttpStatusCode AddCategory(Category category)
{    
    var serializedObject = JsonConvert.SerializeObject(category, new JsonSerializerSettings() { NullValueHandling = NullValueHandling.Ignore });
    var request = new HttpRequestMessage(HttpMethod.Post, string.Concat(CORE_URL, "Categories"));
    request.Content = new StringContent(serializedObject, Encoding.UTF8, "application/json");
    var response = client.SendAsync(request).Result;
    return response.StatusCode;
}

JSON.NET capabilities are used to serialize the object that needs to be inserted. The POST request is executed against the standard table URL, with the UTF8 encoded JSON string. Since the client is already carrying the basic authentication header, all that needs to be done is calling the SendAsync function.

Updating a category follows the same approach, though a PATCH method is used for the request and the URL contains the index of the category that needs to be updated:

public HttpStatusCode UpdateCategory(Category category)
{    
    var request = new HttpRequestMessage(new HttpMethod("PATCH"), string.Concat(CORE_URL, "Categories", "/", category.id));    
    var serializedObject = JsonConvert.SerializeObject(category);
    request.Content = new StringContent(serializedObject, Encoding.UTF8, "application/json");
    var response = client.SendAsync(request).Result;
    return response.StatusCode;
}

To delete a category from the data store, one simply needs to pass a parameter to it that identifies the index of the category that needs to be removed:

public HttpStatusCode DeleteCategoryFromId(int categoryId)
{    
    var request = new HttpRequestMessage(HttpMethod.Delete, string.Concat(CORE_URL, "Categories", "/", categoryId));    
    var response = client.SendAsync(request).Result;
    return response.StatusCode;
}

For images, the same methods can be used, with the Images table passed as the name for the target in the composite URL. Let’s now get back to working on some of the views. A static category list is not fun, so let’s create a way to add new categories. Right click on the Views/Home folder and select Add View:

A great thing about the view creation process in Visual Studio is the fact that you are able to use a basic scaffold template for a strongly-typed view. In this case, I am associating it with a Category class and using the Create template. I now need to modify the controller code to process requests to AddCategory. I need to handle two types of requests, GET and POST, because the view will be displayed to both add an item and submit an item:

public ActionResult AddCategory()
{    
    return View();    
}

[HttpPost]
public ActionResult AddCategory(Category category)
{    
    if (ModelState.IsValid)    
    {    
        engine.AddCategory(category);    
        return RedirectToAction("MainView");    
    }
    
    return View();
}

For a GET request, I am simply returning the view. For a POST view, I am adding the category that was defined by the bound model through the local DataEngine instance, after which the user is redirected to the main view. But we also need to add an ActionResult for the MainView to obtain the list of items that are currently in the Categories table:

public ActionResult MainView()
{    
    var categories = engine.GetAllCategories();    
    return View(categories);
}

The DataEngine instance will return all categories in an IEnumerable<Category> form that are passed as the model for the main view. The layout of MainView.cshtml can be as simple as a table:

@{    
    ViewBag.Title = "Coding4Fun Dynamic Lockscreen";    
}

<h2>Coding4Fun Dynamic Lockscreen - Categories</h2>

<table>
<tr>
<td>
<b>ID</b>
</td>
<td>
<b>Category Name</b>
</td>
</tr>

@foreach (var p in Model)
{    
    <tr>    
    <td>
    @p.id
    </td>
    <td>
    @p.Name
    </td>
    <td>
@Html.ActionLink("Images", "Images", new { categoryId = p.id })
    </td>
    <td>
@Html.ActionLink("Edit", "EditCategory", new { categoryId = p.id })
    </td>
    <td>
@Html.ActionLink("Delete", "DeleteCategory", new { categoryId = p.id })
    </td>
    </tr>
}

</table>

@Html.ActionLink("Add Category", "AddCategory")

The ActionLink helper allows me to invoke a view and, if necessary, pass specific parameters to it (e.g., when I need to identify the category that needs to be deleted or edited). Some of the views listed here are not yet created, but I can easily use placeholder names in any case.

The ultimate result for the main page will look like this:

Notice that you are also able to add new categories now by clicking on the Add Category link on the bottom. This will redirect you to the AddCategory view that we created:

Let’s see how to implement the category editing in the web frontend. First of all, create a new view in Views/Home and name it EditCategory. Use the Edit scaffold template. Like AddCategory, EditCategory needs to be handled in two separate ways for GET and POST requests in the controller:

public ActionResult EditCategory(int categoryId)
{    
    Category category;    
    category = engine.GetCategoryById(categoryId);
    if (category != null)
       return View(category);
    return View("MainView");
}

[HttpPost]
public ActionResult EditCategory(Category category)
{    
    if (ModelState.IsValid)    
    {    
        engine.UpdateCategory(category);    
        return RedirectToAction("MainView");
    }
    
    return View();
}

For a GET request, we need to identify the category that needs to be added by its index, so we are using a categoryId argument passed to the view, which is later used by the DataEngine instance to retrieve the category from the data store. For a POST action, the implementation for UpdateCategory from above is used, where a PATCH request is run with the serialized object bound to the view.

For the Delete action, no additional view is necessary but the controller still needs a handler, so we can use a snippet like this:

public ActionResult DeleteCategory(int categoryId)
{    
    engine.DeleteCategoryFromId(categoryId);    
    return RedirectToAction("MainView");
}

You can use the same approach to add, delete, and edit items in the list of images. For adding images, however, you might want to pass the category identifier. When images are listed after the category has been selected, it is necessary to provide a way to identify the category to which new entities should be added. To do this, we can. in the main controller. pass the category index to the view when the Images action is being triggered:

public ActionResult Images(int categoryId)
{    
    var images = engine.GetImagesByCategoryId(categoryId);    
    if (images != null)
    {    
        ViewData["CID"] = categoryId;    
        return View(images);
    }
    
    return View("MainView");
}

Afterwards, the categoryId value can be obtained by using the CID key for ViewData inside the view itself.

Let’s now take a look at how images are represented for each category. I created a custom view to list all the images associated with the Images category. If you look above at the controller code, you will notice that I am passing the category ID, through which the image set query is executed, and the returned collection is set as the bound model:

public ActionResult Images(int categoryId)
{    
    var images = engine.GetImagesByCategoryId(categoryId);    
    if (images != null)
    {    
        ViewData["CID"] = categoryId;    
        return View(images);
    }
    
    return View("MainView");
}

When an image needs to be added, call the AddImage view. In HomeController.cs, it carries implementations for both GET and POST requests:

public ActionResult AddImage(int categoryId)
{    
    Image image = new Image();    
    image.CategoryID = categoryId;
    return View(image);    
}

[HttpPost]
public ActionResult AddImage(HttpPostedFileBase file, Image image)
{    
    if (file != null && file.ContentLength > 0)    
    {    
        var fileName = Path.GetFileName(file.FileName);    
        var path = Path.Combine(Server.MapPath("~/Uploads"), image.CategoryID.ToString(), fileName);
        string dirPath = Path.GetDirectoryName(path);
        
        if (!Directory.Exists(dirPath))
            Directory.CreateDirectory(dirPath);
        
        file.SaveAs(path);

        string applicationUrl = string.Format("{0}://{1}{2}",        
            HttpContext.Request.Url.Scheme,
            HttpContext.Request.ServerVariables["HTTP_HOST"],
            (HttpContext.Request.ApplicationPath.Equals("/")) ? string.Empty : HttpContext.Request.ApplicationPath
        );
        
        image.URL = Path.Combine(applicationUrl, "Uploads", image.CategoryID.ToString(), fileName);
    }
    
    if (ModelState.IsValid && image.URL != null)
    {    
        engine.AddImage(image);    
        return RedirectToAction("Images", new { categoryID = image.CategoryID });
    }
    
    return View();
}

When a GET request is executed against the AddImage endpoint, I pass the category ID as the flag, signaling which category the image should be included in. When a POST request is executed, it can go two ways—either the user is passing an existing link to a hosted image or the user is uploading his own image to the local server. When an upload is inbound, HttpPostedFileBase carries the content that needs to be pushed to the server.

The upload component on the view itself is done by creating a form with a file input:

<h2>Or you could upload your own file: </h2>

@if (Model != null)
{    
    using (Html.BeginForm("AddImage", "Home", FormMethod.Post, new { enctype = "multipart/form-data", image = Model }))
    {    
        @Html.HiddenFor(model => model.CategoryID);    
        <input type="file" name="file" />
        <input type="submit" value="OK" />
    }
}

If there is no file selected, the system assumes that the user just decided to add an existing URL.

It’s important to mention that the upload workflow relies on the availability of the Upload folder. It is created by default when the project is deployed to the server, but you also need to make sure that the ASP.NET user on the machine where IIS is located has the appropriate write permission for the folder.

The Windows Phone 8 Application Foundation

Create a new Windows Phone 8 application and add a reference to Windows Azure Mobile Services Managed Client. It should be available in the Extensions section if you installed the Windows Azure Mobile Services SDK as I mentioned at the beginning of the article:

In App.xaml.cs you need to create an instance of MobileServiceClient that will be used as the central connection point to the database. Notice that I am using the predefined AMS and API KEY string constants:

public static MobileServiceClient MobileService =
new MobileServiceClient(AuthConstants.AmsUrl, AuthConstants.AmsApiKey);

The mobile application should also carry the data models for both the categories and images. That said, we can reorganize those a bit for a more convenient data binding layout. To ensure that we can reuse the classes from different application components, I am once again using the Coding4Fun.Lockscreen.Core project.

Create a new folder called Models and add a new class called Category:

using System.Collections.ObjectModel;

namespace Coding4Fun.Lockscreen.Core.Models
{    
    public class Category    
    {    
        public Category()    
        {    
            Images = new ObservableCollection<Image>();    
        }
    
        public int? id { get; set; }    
        public string Name { get; set; }

        public ObservableCollection<Image> Images { get; set; }
        
        public override string ToString()        
        {    
            return Name;    
        }
    }
}

We are still relying on a nullable index value, but now there is an ObservableCollection for images. The reason for using this specific collection type is because with an ObservableCollection, binding updates are performed automatically when new items are added or removed, therefore cutting the need to implement the notification mechanism.

The ToString function is overridden to simplify data extraction on binding. When a collection with categories will be hooked to a list, for example, I don’t have to create a converter or a property link.

For the Image model, create a new class called Image in the same Models folder:

namespace Coding4Fun.Lockscreen.Core.Models
{    
    public class Image    
    {    
        public int? id { get; set; }
        public string URL { get; set; }
        public string Name { get; set; }
        public int CategoryID { get; set; }    
    }
}

Application Workflow & Storage

Let’s talk about how image categories will be handled in the application. On application startup, the database is queried for the available categories and each of them is listed on the home screen. If the user taps on one of the categories, the database is queried for the images that are associated with the category index.

However, the user should also be able to create his own custom categories that will only be available in-app. Those categories can carry images from multiple other categories, if necessary, with the default reference set to the internal storage.

Since we are working with local storage, let’s create a helper class called LocalStorageHelper in the Coding4Fun.Lockscreen.Core project in the Storage folder. This class will carry basic read and write functions, allowing us to store data internally:

public static class LocalStorageHelper
{    
    public async static void WriteData(string folderName, string fileName, byte[] content)    
    {    
        IStorageFolder rootFolder = ApplicationData.Current.LocalFolder;
        
        if (folderName != string.Empty)    
        {    
            rootFolder = await rootFolder.CreateFolderAsync(folderName,    
            CreationCollisionOption.OpenIfExists);    
        }
        
        IStorageFile file = await rootFolder.CreateFileAsync(fileName, CreationCollisionOption.ReplaceExisting);
        using (var s = await file.OpenStreamForWriteAsync())
        {    
            s.Write(content, 0, content.Length);    
        }
    }
    
    public static async void ClearFolder(string folderName)
    {    
        var folder = await ApplicationData.Current.LocalFolder.GetFolderAsync(folderName);    
        if (folder != null)
        {    
            foreach (IStorageFile file in await folder.GetFilesAsync())    
            {    
                await file.DeleteAsync();    
            }
        }
    }
    
    public static async Task<string> ReadData(string fileName)
    {    
        byte[] data;    
        StorageFolder folder = ApplicationData.Current.LocalFolder;
        StorageFile file = await folder.GetFileAsync(fileName);
        using (Stream s = await file.OpenStreamForReadAsync())
        {        
            data = new byte[s.Length];    
            await s.ReadAsync(data, 0, (int)s.Length);
        }
        
        return Encoding.UTF8.GetString(data, 0, data.Length);
    }    
}

Notice that I am using the newly-introduced StorageFolder/StorageFile capabilities. If you worked with Windows Store application development, you are probably already familiar with them. Application.Current.LocalFolder gives me direct access to the local directory. which can be modified from within the application itself. It works in a manner similar to IsolatedStorageFile in Windows Phone 7, but with more flexibility when it comes to creating new folders and files and well doing file sweeps.

As I mentioned above, there will be internal data stored as XML. For this purpose, I need a class that carries serialization and deserialization routines, and I can simplify this task by using the Coding4Fun Toolkit Serialize.Save<T> and Serialize.Open<T> capabilities. Calls to these functions allow flexible serialization, where by default the static class is not aware of the serialization type, but is instead able to dynamically infer it from the incoming data. Once the byte layout is obtained for the content, I use the LocalStorageHelper class to write it to a file.

As there are multiple UI items that need to be bound to collections and object instances, I have a CentralBindingPoint class in my main project that is my main view model (it implements INotifyPropertyChanged). It implements the singleton pattern, so that the main instance is created on initialization and is subsequently re-used as necessary:

using Coding4Fun.Lockscreen.Core.Models;
using System;
using System.Collections.ObjectModel;
using System.ComponentModel;

namespace Coding4Fun.Lockscreen.Mobile
{    
    public class CentralBindingPoint : INotifyPropertyChanged    
    {    
        static CentralBindingPoint instance = null;    
        static readonly object padlock = new object();
        
        public CentralBindingPoint()
        {    
            Categories = new ObservableCollection<Category>();    
            CustomCategories = new ObservableCollection<Category>();    
        }
        
        public static CentralBindingPoint Instance
        {    
            get    
            {    
                lock (padlock)    
                {    
                    if (instance == null)    
                    {    
                        instance = new CentralBindingPoint();    
                    }
                
                    return instance;        
                }
            }
        }
        
        private ObservableCollection<Category> _categories;
        public ObservableCollection<Category> Categories
        {    
            get    
            {    
                return _categories;    
            }
            set
            {    
                if (_categories != value)        
                {    
                    _categories = value;    
                    NotifyPropertyChanged("Categories");
                }
            }
        }
        
        private ObservableCollection<Category> _customCategories;
        public ObservableCollection<Category> CustomCategories
        {    
            get    
            {    
                return _customCategories;    
            }
            set
            {    
                if (_customCategories != value)    
                {    
                    _customCategories = value;    
                    NotifyPropertyChanged("CustomCategories");
                }        
            }
        }
    
        private Category _currentCategory;    
        public Category CurrentCategory
        {    
            get    
            {        
                return _currentCategory;    
            }
            set
            {    
                if (_currentCategory != value)    
                {    
                    _currentCategory = value;    
                    NotifyPropertyChanged("CurrentCategory");
                }
            }
        }
        
        public event PropertyChangedEventHandler PropertyChanged;
        private void NotifyPropertyChanged(String info)
        {    
            if (PropertyChanged != null)    
            {    
                System.Windows.Deployment.Current.Dispatcher.BeginInvoke(    
                () =>
                {    
                    PropertyChanged(this, new PropertyChangedEventArgs(info));    
                });
            }
        }
    }
}

On the main page, I create a Pivot-based layout to have an easy way to transition between the web collections (categories) and the local ones:

For each of the collection types, there is a ListBox with a custom DataTemplate assigned for each item. The items are obtained from the Categories collection for web sets and the CustomCategories collection for local sets, both in the CentralBindingPoint view model.

The categories are loaded with the help of the DataEngine class that I added in the Data folder in the main application project. It is a wrapper for the Azure Mobile Services data operations, allowing me to aggregate the list of categories and images, given that I know the category index:

public class DataEngine
{    
    async public Task<List<Category>> GetCategoryList()    
    {    
        IMobileServiceTable<Category> table = App.MobileService.GetTable<Category>();    
        List<Category> data = await table.ToListAsync();
        
        return data;
    }
    
    async public Task<List<Image>> GetImagesByCategoryId(int categoryId)
    {    
        IMobileServiceTable<Image> table = App.MobileService.GetTable<Image>();    
        List<Image> data = await table.Where(x => x.CategoryID == categoryId).ToListAsync();
        
        return data;
    }
}

When the main page loads, I use the local DataEngine instance to call GetCategoryList and obtain a List<Category> collection that is subsequently transformed into an ObservableCollection through one of the default constructors:

async void MainPage_Loaded(object sender, RoutedEventArgs e)
{    
    CentralBindingPoint.Instance.Categories = new ObservableCollection<Category>(await dataEngine.GetCategoryList());    
}

When a category is selected in the web sets list, I assign the selected item as the current category and navigate to the ImageSetPage.xaml page that will display the associated images:

async void ListBox_SelectionChanged_1(object sender, System.Windows.Controls.SelectionChangedEventArgs e)
{    
    var box = (ListBox)sender;
    
    if (box.SelectedItem != null)    
    {    
        Category selectedCategory = (Category)box.SelectedItem;    
        selectedCategory.Images = new ObservableCollection<Coding4Fun.Lockscreen.Core.Models.Image>
        (await dataEngine.GetImagesByCategoryId((int)selectedCategory.id));
        
        CentralBindingPoint.Instance.CurrentCategory = selectedCategory;
        NavigationService.Navigate(new Uri("/ImageSetPage.xaml", UriKind.Relative));
    }
}

Notice that the images are not loaded at the same time as the categories; rather, they’re loaded only when a category has been selected, hence the GetImagesByCategoryId call on selection.

For a custom set, the procedure is pretty much the same, the only difference being the fact that image references are already present since those were deserialized from the local storage:

private void lstCustomSets_SelectionChanged_1(object sender, SelectionChangedEventArgs e)
{    
    var box = (ListBox)sender;
    
    if (box.SelectedItem != null)    
    {    
        Category selectedCategory = (Category)box.SelectedItem;    
        CentralBindingPoint.Instance.CurrentCategory = selectedCategory;
        NavigationService.Navigate(new Uri("/ImageSetPage.xaml", UriKind.Relative));
    }
}

In ImageSetPage.xaml I use a ListBox with a WrapPanel in the ItemsPanelTemplate, which ensures that I can have only two images in a row and any additions will be wrapped, with a fixed row length. You can get that control from the WPToolkit (formerly known as Silverlight Toolkit for Windows Phone, available on NuGet).

Here is the basic XAML layout:

<ListBox 
    SelectionMode="Single"
    Margin="24"
    x:Name="lstImages" SelectionChanged="lstImages_SelectionChanged_1"
    ItemsSource="{Binding Path=Instance.CurrentCategory.Images,
    Source={StaticResource CentralBindingPoint}}"
    ItemTemplate="{StaticResource ListItemTemplate}">
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <toolkit:WrapPanel ItemWidth="216" ItemHeight="260"/>
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
</ListBox>

Now that we have a basic skeleton for the incoming data, let’s see how it can be transformed into a live lockscreen, on which wallpapers can be cycled. In the ImageSetPage.xaml page I have a button in the application bar that allows me to set the current category as the source for the switching wallpapers.

Currently, each Image instance carries an image URL and the images can be located anywhere outside the application. This can cause problems with the wallpaper setting process, however, since the API only allows local images to be set as background. This means that I need to download each image to the local application folder:

private async void btnSetStack_Click_1(object sender, EventArgs e)
{    
    var isProvider = Windows.Phone.System.UserProfile.LockScreenManager.IsProvidedByCurrentApplication;
    
    if (!isProvider)    
    {    
        var op = await Windows.Phone.System.UserProfile.LockScreenManager.RequestAccessAsync();    
        isProvider = op == Windows.Phone.System.UserProfile.LockScreenRequestResult.Granted;
    }
    
    if (isProvider)
    {    
        downloadableItems = new List<string>();    
        fileItems = new List<string>();

        foreach (var image in CentralBindingPoint.Instance.CurrentCategory.Images)        
        {    
            downloadableItems.Add(image.URL);    
            fileItems.Add(Path.GetFileName(image.URL));    
        }
        
        SerializationHelper.SerializeToFile(fileItems, "imagestack.xml");
        LocalStorageHelper.ClearFolder("CurrentSet");
        DownloadImages();
        grdDownloading.Visibility = System.Windows.Visibility.Visible;
    }
}

First of all, I need to make sure that the application can set a lockscreen background and is registered in the OS as a provider. The application needs to state its intent to be able to access the wallpaper by adding this snippet to the WMAppManifest.xml, right after the Tokens node:

<Extensions>
      <Extension ExtensionName="LockScreen_Background" ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}" TaskID="_default" />
</Extensions>

downloadableItems is a collection that represents the download queue. fileItems contains the local file names for each image that is about to be downloaded and will be serialized and used in the background agent to iterate through the category files. Whenever the download process is started, an overlay becomes visible to notify the user that the image acquisition process is in progress.

Also, notice the fact that I am calling LocalStorageHelper.ClearFolder, passing the name of the folder as the first argument. I do not want to keep images for sets that are not active, therefore when a new set is selected, the currently stored images are deleted from the CurrentSet folder and replaced by the ones that are about to be downloaded. The implementation of the ClearFolder function looks like this:

public static void ClearFolder(string folderName
{    
    if (store.DirectoryExists(folderName))    
    {    
        foreach (string file in store.GetFileNames(folderName + "\\*.*"))    
        {    
            store.DeleteFile(folderName + "\\" + file);    
        }
    }
}

Once the file names are stored in imagestack.xml, the image contents are downloaded via DownloadImages:

void DownloadImages()
{    
    WebClient client = new WebClient();    
    string fileName = Path.GetFileName(downloadableItems.First());
    client.OpenReadAsync(new Uri(downloadableItems.First()));
    client.OpenReadCompleted += (sender, args) =>
    {    
        Debug.WriteLine("Downloaded " + fileName);    
        LocalStorageHelper.WriteData("CurrentSet", fileName, StreamToByteArray(args.Result));
        downloadableItems.Remove(downloadableItems.First());
        if (downloadableItems.Count != 0)
            DownloadImages();
        else
        {    
            grdDownloading.Visibility = System.Windows.Visibility.Collapsed;    
            LocalStorageHelper.CycleThroughImages();
            
            //ScheduledActionService.LaunchForTest("LockscreenChanger", TimeSpan.FromSeconds(5));
        }
    };
}

Here you can see that I am making a call to LocalStorageHelper.CycleThroughImages—a function that reads the file that contains the current set and picks the first image, assigning it to be the current wallpaper and then pushing it to the back of the list, making the succeeding image the next in line for the wallpaper:

public static void CycleThroughImages()
{    
    List<string> images = Coding4Fun.Phone.Storage.Serialize.Open<List<string>>("imagestack.xml");    
    if (images != null)
    {    
        string tempImage = images.First();    
        Uri currentImageUri = new Uri("ms-appdata:///Local/CurrentSet/" + tempImage, UriKind.Absolute);
        Windows.Phone.System.UserProfile.LockScreen.SetImageUri(currentImageUri);
        images.Remove(tempImage);
        images.Add(tempImage);
        Coding4Fun.Phone.Storage.Serialize.Save<List<string>>("imagestack.xml", images);
    }
}

You might be wondering why I’m not using Queue<T> for this. After all, Enqueue and Dequeue would make things a bit easier. The problem is that a Queue instance cannot be directly serialized without being transformed to a flat list. Therefore, I am sticking to minimal resource processing by manipulating a List<T> instance instead.

The recursive image download method runs until the download queue is emptied, after which the overlay is hidden.

Background Agent

At this point, we have the images locally stored and listed in an XML file. If the user accepted the system prompt, the application has also been registered as a lockscreen background provider, but there is not yet a single piece of code that would actually set the wallpaper cycle. For that, create a new Background Agent project in your solution. I named mine Coding4Fun.Lockscreen.Agent.

The OnInvoke function in ScheduledAgent.cs is executed at 30-minute intervals. This is a time limit defined by the PeriodicTask background agent type that we’ll be using here. You need to add the following snippet to it:

protected override void OnInvoke(ScheduledTask task)
{    
    var isProvider = Windows.Phone.System.UserProfile.LockScreenManager.IsProvidedByCurrentApplication;    
    if (isProvider)
    {    
        LocalStorageHelper.CycleThroughImages();    
    }
    NotifyComplete();
}

As with the download snippet, I am ensuring that before I attempt to change the wallpaper the application is a registered provider. Otherwise, an exception will be thrown and the background agent will crash. The bad thing about periodic tasks crashing is the fact that once two consecutive crashes occur, the task is removed from the task queue and the backgrounds will not be changed.

If the application is a provider, call CycleThroughImages to set the new background and push the old one to the end of the list. To make sure that a different image is selected each time, the original deserialized list is modified, where the first image now becomes last, switching the stack up, after which it is serialized back into imagestack.xml.

The background agent needs to be registered in the WMAppManifest.xml. Inside the Tasks node, add an ExtendedTask:

<ExtendedTask Name="LockscreenChangerTask">
    <BackgroundServiceAgent Specifier="ScheduledTaskAgent"
        Name="LockscreenChanger"
        Source="Coding4Fun.Lockscreen.Agent"
        Type="Coding4Fun.Lockscreen.Agent.ScheduledAgent" />
</ExtendedTask>

Also, when the application starts, you need to ensure that the task is registered, and register it if it isn’t yet. Use the Application_Launching event handler for this task:

private void Application_Launching(object sender, LaunchingEventArgs e)
{    
    string taskName = "LockscreenChanger";    
    var oldTask = ScheduledActionService.Find(taskName) as PeriodicTask;

    if (oldTask != null)
    {    
        ScheduledActionService.Remove(taskName);    
    }
    
    PeriodicTask task = new PeriodicTask(taskName);
    task.Description = "Change lockscreen wallpaper.";
    
    ScheduledActionService.Add(task);    
    LoadCustomCategories();    
}

Here, LoadCustomCategories will deserialize the existing custom categories, so that those can be shown in the main page after the application starts:

private async void LoadCustomCategories()
{    
    try    
    {    
        CentralBindingPoint.Instance.CustomCategories =    
        (ObservableCollection<Category>)await SerializationHelper.DeserializeFromFile(
        typeof(ObservableCollection<Category>), "customcat.xml");
    }
    catch
    {    
        Debug.WriteLine("No customcat.xml - no registered custom categories.");    
    }
}

Now the backgrounds will automatically change based on the web sets that you will activate every 30 minutes.

Working with Custom Categories

Let’s create some custom sets. To manage user input, I leverage the CustomMessageBox control available in the Windows Phone Toolkit. It has enough flexibility to let me choose between adding a TextBox control, to have the user create the new category or use a ListPicker to show the available custom categories in a consistent UI layout.

When the user decides to create a new category, he taps the plus button in the application bar on the main page:

The implementation for the call is simple:

private void btnSetStack_Click_1(object sender, EventArgs e)
{    
    TextBox textBox = new TextBox();    
    CustomMessageBox box = new CustomMessageBox()
    {    
        Caption = "Add Custom Category",    
        Message = "Enter a unique name for the new category.",
        LeftButtonContent = "ok",
        RightButtonContent = "cancel",
        Content = textBox
    };
    
    box.Dismissed += (s, boxEventArgs) =>
    {    
        if (boxEventArgs.Result == CustomMessageBoxResult.LeftButton)    
        {    
                    if (!string.IsNullOrWhiteSpace(textBox.Text))    
                    {    
                        var categoryCheck = (from c in CentralBindingPoint.Instance.CustomCategories    
                        where
                        c.Name == textBox.Text
                        select c).FirstOrDefault();
                        
                        if (categoryCheck == null)
                        {    
                            Category category = new Category() { Name = textBox.Text };
                            CentralBindingPoint.Instance.CustomCategories.Add(category);
                            Coding4Fun.Toolkit.Storage.Serialize.Save<ObservableCollection<Category>>(
                            "customcat.xml", CentralBindingPoint.Instance.CustomCategories);
                        }
                        else
                        {    
                            MessageBox.Show("Add Custom Category",    
                            "This category name was already taken!",
                            MessageBoxButton.OK);
                        }
                    }
        }        
    };
    
    box.Show();    
}

When the message box is dismissed, I check which button is pressed to take the appropriate course of action. Let’s assume that the user decided to add the new category—we need to check and make sure that there isn’t already a category with the same name in the existing collection. If there isn’t one, a new Category instance is created, added to the collection in the main view model, and serialized to customcat.xml.

The user also needs to be able to add images from any category to another custom category. To do this, I decided to give the user the option to carry across the image name and URL when he taps on an image in the ImageSetPage.xaml.

Remember, if there are no current custom categories registered, the user should be informed that he should create some first, so the alternative route for the dialog with custom category name selection should be a message box alert:

Here is the snippet that does this:

private void lstImages_SelectionChanged_1(object sender, SelectionChangedEventArgs e)
{    
    if (CentralBindingPoint.Instance.CustomCategories.Count > 0)    
    {    
        if (lstImages.SelectedItem != null)    
        {    
            ListPicker picker = new ListPicker()    
            {    
                Header = "Custom category name:",    
                ItemsSource = CentralBindingPoint.Instance.CustomCategories,
                Margin = new Thickness(12, 42, 24, 18)
            };
            
            CustomMessageBox messageBox = new CustomMessageBox()
            {    
                Caption = "Add To Custom Category",    
                Message = "Select a registered custom category to add this image to.",
                Content = picker,
                LeftButtonContent = "ok",
                RightButtonContent = "cancel"
            };
            
            messageBox.Dismissing += (s, boxEventArgs) =>
            {    
                if (picker.ListPickerMode == ListPickerMode.Expanded)    
                {    
                    boxEventArgs.Cancel = true;    
                }
            };
            
            messageBox.Dismissed += (s2, e2) =>
            {    
                switch (e2.Result)    
                {    
                    case CustomMessageBoxResult.LeftButton:    
                    {    
                        if (picker.SelectedItem != null)    
                        {    
                            Category category = (from c in CentralBindingPoint.Instance.CustomCategories    
                            where c.Name == picker.SelectedItem.ToString()
                            select c).FirstOrDefault();
                            
                            if (category != null)
                            {    
                                category.Images.Add((Coding4Fun.Lockscreen.Core.Models.Image)lstImages.SelectedItem);    
                                Coding4Fun.Toolkit.Storage.Serialize.Save<ObservableCollection<Category>>(
                                "customcat.xml", CentralBindingPoint.Instance.CustomCategories);
                            }
                            
                            lstImages.SelectedItem = null;
                            lstImages.IsEnabled = true;
                        }
                        break;
                    }
            
                    case CustomMessageBoxResult.RightButton:        
                    case CustomMessageBoxResult.None:
                    {    
                        lstImages.SelectedItem = null;                    
                        break;
                    }
                }
            };
            
            messageBox.Show();
        }
    }
    else
    {    
        MessageBox.Show("Add To Custom Category",    
        "Tapping on an image will prompt you to add it to a custom category" + Environment.NewLine +
        "Seems like you don't have any custom categories yet.", MessageBoxButton.OK);    
    }
}

Once the category is selected from the list, the image is added to the Images collection in the Category instance, and the category list is serialized to preserve the changes. There are no restrictions as to which categories can fetch images to other categories—we can even select images from custom categories and include them in other categories. The image can be added multiple times to the same category as well.

Conclusion

With Azure Mobile Services and a managed SDK available for Windows Phone, as well as an open REST API, it is fairly easy to build connected applications on multiple platforms at once without major logic and code base modifications.

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-12-Conclusions

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-11-Hardware-Testing--Debugging

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-10-Charms

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-9-Particle-System

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-8-Element-Interaction

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-7-Animations

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-6-Rendering-Level-Elements

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-5-Creating-Levels

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-4-XAML-Interop

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-3-Basic-Rendering-and-Movement

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-2-Shaders

For the source code, head over to http://fallfury.codeplex.com

Check out the article for this video at http://channel9.msdn.com/coding4fun/articles/Fall-Fury-Part-1-Introduction

For the source code, head over to http://fallfury.codeplex.com

Developing FallFury was a fun and educational activity. Besides the fact that I got to work with an amazing team of people who were willing to assist me with the testing and development, I learned some important points about the development process as a whole and have outlined them in this article.  Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-12-Project-Conclusion.  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

Go Outside Your Comfort Zone

This past summer, I decided to tackle a new challenge—game development. Never before had I built a game from the ground up. Moreover, as I could already find my way around C# code, I decided that I wanted to make C++ the language of choice, and so worked with DirectX instead of XNA. Additionally, the project needed to be constructed with Windows 8 as the target platform and I’d have to rely on the WinRT stack.

The concepts were new to me, but I figured that learning about a new platform and a new language would be more interesting than sticking to my comfort zone. Through FallFury I extended my knowledge about pointers, trigonometry, how DirectX handles a lot of the graphics legwork, and how to write HLSL shaders.

It was a challenging but very rewarding experience.

Communicate

The most important part of any project is communication. There are always people who know more than you in one field or another, so don't hesitate to reach out to other developers and ask questions. Your code is not perfect, so talk about best practices used in production and how you can improve on what you already have—communication should not be limited to your team, floor, or even building.

One bonus of my experience at Microsoft was discovering that a lot of developers, when not in a meeting or in the middle of an important assignment, are more than happy to help a fellow employee with a piece of advice or some code review.

Plan the Small Details

Before you even touch the keyboard to write your first line of code, outline the components of your application and have a general idea of how you’ll implement those components as well as how they’ll interact with each other. It is tempting to start coding and then add or modify features, but doing so will create more problems than it will solve.

Build Small Prototypes

FallFury is a complex project composed out of blocks such as:

• XML level/metadata reader and writer
• The Share and Settings charm components
• SpriteBatch sub-system
• Level renderer
• Screen sub-system
• Menu interaction sub-system

Each block is responsible for its own set of tasks and each can be individually tested with either mocked data or a loose connection to the existing codebase. The necessity for small prototypes comes from individual requirements tied to the platform and possible integration scenarios. For example, when I began development, I created a non-hybrid DirectX project, which meant that if I needed to introduce XAML integration, I had to rewrite small parts of my swap chain preparation stack as well as work with a lot of XAML content in the code-behind. The Settings charm integration heavily relied on XAML, and I would have had to write the popup and control-related code in C#.

Obviously, that was not an option, so I created a hybrid project instead and ported most of my code into the new solution. Lesson learned here: prototype—and prototype early—in order to make sure that what you plan to implement will be implemented in an efficient manner.

Test Often, Test with Other People

When working on an application, it is important to understand the needs and expectations of your target audience, and a big part of this is making sure that the application provides a way for the user to easily learn about an action without a helper booklet. The menu system is a good example of this in FallFury. As I was designing the buttons on my screens, I tried to implement the approach used in games such as Dance Central—the user simply slides the button-panel and it takes him to the screen that was linked to that specific button. However, as I was testing the application with the local development crowd, I noticed a pattern—people were attempting to simply tap the button instead of sliding it. To avoid this confusion, I added a pulsating arrow on the right side of the button in order to highlight the fact that the button should be displaced in order to be activated.

The XML level loading system is another example of how secondary testing improved FallFury. Initial element positioning relied on a given level length, as well as on a ration-based placement. For example, if I wanted to put a button in the middle of the screen, I could position it with a value, such as .5. The level loader would then translate this value relative to the screen size. Rick Barraza was creating some test levels when he notified me about a big flaw—as the level extended, some elements were mis-positioned by a large margin compared to the original intended location. This was because when a level length was reset, the ratio was applied on a larger/smaller value, and some elements would therefore overlap. Ultimately, I rewrote the level structure to rely on pixel values, and designed the level-length to calculate automatically based on the included elements and their size.

Test on Different Hardware

FallFury started with portable hardware in mind. Its original design targeted Windows 8 tablet devices, though it was later decided that the project should support desktop machines as well. That automatically added thousands of possible hardware combinations on which the game might potentially run. Here are just some of the test machines we got to use:

• Samsung Series 7 Slate
• ARM Developer Tablet (Microsoft Surface)
• ASUS EP121 Slate

Each of these machines came with its own specific conditions that had to be accommodated. While Samsung Series 7 Slate featured an accelerometer, at the time of development the ASUS EP121 tablet did not have Windows 8 drivers for its sensor. When I sideloaded the game, I noticed that I could no longer control the character the way I wanted to. Also, though FallFury has keyboard controls, I had to develop controls for machines without keyboards. This is why I came up with the concept of touch-based, on-screen controls.

Moving on to the ARM device, first and foremost I noticed that my shader configurations were not compatible with the platform capabilities. All my testing was done on a machine that supported DirectX Feature Level 10, which was not the case for a low-power ARM machine that supports DirectX Feature Level 9.1. I had to work with some MSDN samples to find a way to properly modify the required shaders so they would work on Windows RT. ARM devices are built with battery life in mind. Therefore, their capabilities are reduced compared to those of a full-sized Windows tablet. This had an impact on the general game performance—some parts of the game, such as particle rendering, were working fine on a desktop machine, but were quite laggy on the ARM tablet. Knowing the possible source of the problem, I had to optimize the particle storage and rendering stack to ensure they didn’t affect the user experience on Windows RT hardware.

There Is Never Enough Time - Learn To Cut

When I started planning FallFury, I worked up a huge list of features. As the deadline approached, however, I noticed that I somewhat underestimated the allocated project time—a lot of time was spent on testing and eliminating bugs in existing features. That was the point at which I had to cut my feature set.

When designing the feature list for your app, make sure that you have a clear vision of which features get the priority and which can be cut if necessary. For example, FallFury was originally planned to be a multiplayer game. Although it was tempting to start working on it as such from the very beginning, I knew that it wasn’t a core feature and that it wouldn’t necessarily affect the general play experience on release day. Ultimately, multiplayer capability was dropped from initial development along with a number of other not-immediately-integral features.

Expect the Unexpected

When allocating time for the project, anticipate situations that might derail the process and cause a delay in the planned delivery date. It is easy to estimate that creating an accelerometer-based motion system will take you a day or two, but you also need to allow for the potential possibility of your code not working as expected, hardware accidents, natural disasters, etc. Doing so will help you focus on the right features at the right time while diminishing the risk of missing the deadline.

Platform Samples Are the Best Documentation - Learn to Read Others’ Code

While building the core of FallFury, I leveraged multiple features that hadn’t yet become mainstream among Windows developers. Therefore, the documentation was scarce and in some instances the only help I could get was internal. Luckily, Microsoft bundled hundreds of samples that demonstrate what the new platform can do. A lot of the development approaches gained during my internship were learned from looking at the official, publicly released sample code. The lesson here: if it's not on MSDN or blogs, check the official developer samples. For example, I used the DirectX sprite drawing sample to see how to build a proper sprite rendering mechanism with behavior similar to the one available in XNA.

Atomic Commits

When I started, source control wasn’t new to me, but there were proper usage practices that I didn’t apply before the internship. One of them is atomic commits, which I learned from Clint Rutkas.

With every new addition to the application, chances are something might go wrong. It could be a faulty third-party assembly, a misplaced class, or a broken reference that brings down the entire solution. If the commits include longer time intervals, for example, you will ultimately have to roll back to a build without a lot of the new functionality. Using atomic commits, however, you’ll be able to avoid unnecessary, redundant work in the case that something goes wrong during development.

A Non-standard Approach Is Not Necessarily a Bad Approach

For loading high scores, I needed the UI layout to display the registered items. To do so, I had could either use data binding or write a simple routine that would generate XAML items on the fly in the code-behind. Data binding is a pretty common practice among XAML developers, so my initial thought was to use that, but I would have had to create a C++ binding harness in addition to the existing data retrieval code. The second approach was much cleaner because it didn’t require me to rewrite or add much code. The lesson here: pick the best approach for the job and don’t blindly follow programming trends.

Focus on the User Experience

At the end of the day, the user doesn’t care whether you wrote the application in native DirectX or XNA, whether you applied the MVVM pattern, or whether you have easily readable code. The user cares about having a great time while playing the game, regardless of its backbone. It’s your goal as a developer to deliver that user experience and ensure that the user feels comfortable with the product. This means that the development cycle goes beyond simply writing code. In FallFury, levels are dynamic, which means the source code doesn’t necessarily need to be modified in order to create a different playable experience. But that experience matters in any case, and level design is a huge part of FallFury’s final product. Users need to be immersed in the game world, so levels must be planned in such as way that the user returns to the game and doesn’t abandon it after a couple of lost rounds.

Conclusion

FallFury was my first major project that I wrote almost entirely in C++, targeting the newly released Windows 8 operating system. Although the development process was challenging, it was proven to be a great educational experience that taught me about the approaches and practices that are used internally at Microsoft.

As previously mentioned, FallFury runs on multiple types of hardware as long as that hardware supports Windows 8. This article describes the project’s general testing and debugging process, including setting the debug configurations and remote debugging.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-11-Hardware-Testing.  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

Remote Debug

When working on an application that targets different machines, it’s probably out of the question to install Visual Studio on each instance and move the solution from one source to another in order to run it and diagnose potential problems. Here is where Remote Tools for Visual Studio 2012 come into play. Microsoft offers you three separate builds—tools for x86 systems, x64 systems, and ARM systems—also known as Surface RT.

Once the tools are running on the machine you want to debug, you have two choices. You can either install the remote debugger as a service, allowing it to constantly run in the background, or you can use the debugger on a per-launch basis. From a developer perspective, the choice doesn’t affect how your application is executed on the remote machine. From a security perspective, however, you need to be sure that you properly configure it so that no unwanted apps are remotely deployed.

Now you can start the Remote Debugger Configuration Wizard:

This works on both the initial start-up and also any subsequent launch as a way to easily and quickly set the necessary remote debugger settings. Specifically, it is useful to configure the machine’s network settings, allowing cross-domain communications for debugging purposes.

Once the wizard is completed, launch the Remote Debugger Monitor. Notice that it lists your machine name and the port on which it’s running. This is necessary for configuring the project to send the package to a remote machine instead of the local one:

The configuration depends on the network settings on both the local machine and the subnet as a whole. For example, in some cases, and especially on domain-joined machines, remote debugging is better done with the authentication disabled. Windows Authentication is used by default.

Since FallFury is a C++ project, the configuration for a remote session is different than, say, that of a C# Windows Store application. To configure the session, right click on the project in Solution Explorer and open the Debugging section. Make sure that Remote Machine is selected as the type of debugger to launch:

Next, specify the machine name as well as whether the current session will require authentication:

If you cannot specify the machine name, use the direct IPv4 address of that computer, minus the port (unless you’ve explicitly set it to a port other than 4016, which is the assumed default). Once the source machine connects to the remote one, you will see Visual Studio performing the deployment:

Configurations

As a matter of convenience, it is always good to have different debug configurations that will define how your projects are built, especially if the project targets multiple platforms (such as ARM and x86). Visual Studio provides a Configuration Manager that can be accessed from the debug target dropdown:

FallFury includes two separate projects—the game core, and the C#-based XML reader. Both need to be explicitly associated with separate target platforms in order to be correctly debugged. For that, profiles were created for both local and remote sessions:

As with standard Debug/Release configurations, the ones shown above determine whether the project will carry debug symbols and support debugging commands. It is important to mention that as you switch configurations, you must be careful how you configure the graphic shaders. For each shader in the container folder, explicitly set the HLSL shader type and model. Otherwise the application deployment will fail:

Remote Profiling

Last but not least, when working with different hardware configurations it might be useful to perform application profiling or performance review. Fortunately, Visual Studio also provides this capability through the vsperf tool, which is already integrated in the IDE if you are using Visual Studio 2012 Professional or above.

To initiate a profiling session on a remote device, the Remote Debugger Monitor must be active. Make sure that the Remote Machine debug target is selected, and go to Analyze > Start Performance Analysis:

On the remote machine, allow the vsperf process to run with administrative privileges. Once the profiling session completes and the data is analyzed, you can review the same performance indicators as you would when having a standard application run the profiler on the local machine:

Conclusion

Testing hardware outside the boundaries of a desktop machine is often a necessity, especially if the application relies on specific sensors, such as NFC, touch, or accelerometer. The remote debugging process is fairly streamlined and intuitive, with developing a proper network configuration allowing communication between machines requiring the most significant amount of effort. If you have problems getting the debugger to work, consult this article on MSDN.

With the release of the Windows 8 operating system, applications are now able to easily integrate with each other and have a unified way to control their workflow through unique system-wide contracts called Charms. Out of the multitude of available options, FallFury leverages two charms—Share contract and Settings. This article describes how the integration is implemented.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-10-Charms .  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

The Share Contract

When a user achieves a specific score in the game, he might decide to share it with his social circle. In Charms, that’s the purpose of the Share contract, which integrates directly with the OS.

Windows Store applications have the capability to expose their sharing capabilities and register as a share target. For example, if there is a Twitter client out, it can register itself as an app through which content can be shared. FallFury, on the other hand, acts as a consumer that aggregates existing share targets and lets the user pick the one through which he wants to let the message out:

Let’s take a look at how this process is built in the code-behind. The core is located in DirectXPage.xaml.cpp—the class responsible for XAML content manipulation in FallFury. First and foremost, you need to get the current instance of the DataTransferManager class:

auto dataTransferManager = Windows::ApplicationModel::DataTransfer::DataTransferManager::GetForCurrentView();

Consider this a proxy that allows you to pass content between your app and other Windows Store apps that are executed in the context of the same sandbox. As the instance is obtained, hook it to the DataRequested event handler that will handle the scenario where the user invoked the sharing capability:

dataTransferManager->DataRequested += ref new 
    TypedEventHandler<Windows::ApplicationModel::DataTransfer::DataTransferManager^,
    Windows::ApplicationModel::DataTransfer::DataRequestedEventArgs^>(this, &DirectXPage::OnShareDataRequested);

In the OnShareDataRequested, specify the information that goes into the sharing popup:

void DirectXPage::OnShareDataRequested(Windows::ApplicationModel::DataTransfer::DataTransferManager^ manager,Windows::ApplicationModel::DataTransfer::DataRequestedEventArgs^ params)
{
    auto request = params->Request;
    request->Data->Properties->Title = "Share Score";
    request->Data->Properties->Description = "Tell your friends how much you scored in [DEN'S PROJECT]!";
    request->Data->SetText("I just scored " + StaticDataHelper::Score.ToString() + " in [DEN'S PROJECT]! Beat me! http://dennisdel.com");
}

From that point, the control is in the user’s hand. The application cannot force the share, so unless you implement a direct API hook to a social service, the Share charm will only expose the endpoints available for sharing and will let you set the shareable content. You also don’t have to worry about the way the content will be shared—that will be handled by the target application:

You can show the popup triggered by the Share charm from your application without having the user open the Charms Bar. To do this, call the ShowShareUI method:

void DirectXPage::ShareTopScore_Selected(MenuItem^ sender, Platform::String^ params)
{
    Windows::ApplicationModel::DataTransfer::DataTransferManager::ShowShareUI();
}

This is exactly what the Share button does in the screenshot above. You should make this behavior predictable.

The Settings Charm

As you just saw, integrating basic sharing capabilities in FallFury is not too complicated. Working with settings is also a fairly easy task, though it involves some XAML work. While with sharing capabilities the work focused mostly on OS-based endpoints and application-specific popups, settings allow for full control over how they’re displayed.

For all Windows Store applications, settings should be handled via the Settings charm and not through dedicated application screens. Consider which settings that directly affect the user experience might be changed in FallFury:

• Music and SFX – the user can enable or disable music and sound effects, as well as control their volume.
• Accelerometer – depending on personal preferences, the user might decide to disable the accelerometer (it is enabled by default). The accelerometer can also be inverted—if the device is tilted to the right, the character will move to the left and vice-versa. Last but not least, even with dynamic screen rotation enabled on the device, the user can disable that rotation on the application level and lock the screen to one orientation, such as portrait or landscape.
• Character Movement – the character can be easily controlled via touch (swipe) or mouse. This behavior is enabled by default, but if the user decides to only use the mouse to direct shells, he can easily disable this feature here.

As seen in the image above, the operating system provides the basic shell used to list the possible settings. Once one option is selected, however, further UI displays are delegated to the developer.

As with the share UI, the settings UI can be shown to the user from the application and not from the Charms Bar. Here is how to do this:

void DirectXPage::Settings_Selected(MenuItem^ sender, Platform::String^ params)
{
    SettingsPane::GetForCurrentView()->Show();
}

SettingsPane is the core class that handles the settings display. It does not control how settings are stored or activated. When the main page loads, you need to make sure that you hook the current SettingsPane to a CommandRequested event handler. It will be triggered when the Settings capability is invoked:

SettingsPane::GetForCurrentView()->CommandsRequested += ref new TypedEventHandler<SettingsPane^, SettingsPaneCommandsRequestedEventArgs^>(this, &DirectXPage::OnSettingsRequested);

OnSettingsRequested is the function where the core setting selections are defined and hooked to their own event handlers:

void DirectXPage::OnSettingsRequested(Windows::UI::ApplicationSettings::SettingsPane^ settingsPane, Windows::UI::ApplicationSettings::SettingsPaneCommandsRequestedEventArgs^ eventArgs)
{
    if (m_renderer->CurrentGameState == GameState::GS_PLAYING)
            StaticDataHelper::IsPaused = true;
    
    UICommandInvokedHandler^ handler = ref new UICommandInvokedHandler(this, &DirectXPage::OnSettingsSelected);
    
        SettingsCommand^ generalCommand = ref new SettingsCommand("musicSfx", "Music & SFX", handler);
        eventArgs->Request->ApplicationCommands->Append(generalCommand);
    
    SettingsCommand^ accelerometerCommand = ref new SettingsCommand("accelerometer", "Accelerometer", handler);
    eventArgs->Request->ApplicationCommands->Append(accelerometerCommand);
    
    SettingsCommand^ charMovementCommand = ref new SettingsCommand("charMovement", "Character Movement", handler);
    eventArgs->Request->ApplicationCommands->Append(charMovementCommand);
}

Each SettingsCommand is an item in the list displayed in the settings pane. When one is selected, OnSettingsSelected is called:

void DirectXPage::OnSettingsSelected(Windows::UI::Popups::IUICommand^ command)
{
    if (command->Id->ToString() == "musicSfx")
    {
        stkMusicSfx->Width = 346.0f;
        grdSubMusicSfx->Height = m_renderer->m_renderTargetSize.Height;
        stkMusicSfx->IsOpen = true;
    }
    else if (command->Id->ToString() == "accelerometer")
    {
        stkAccelerometerSettings->Width = 346.0f;
        grdAccelerometerSettings->Height = m_renderer->m_renderTargetSize.Height;
        stkAccelerometerSettings->IsOpen = true;
    }
    else if (command->Id->ToString() == "charMovement")
    {
        stkCharacterMovement->Width = 346.0f;
        grdCharacterMovement->Height = m_renderer->m_renderTargetSize.Height;
        stkCharacterMovement->IsOpen = true;
    }

    WindowActivationToken = Window::Current->Activated += ref new WindowActivatedEventHandler(this, &DirectXPage::OnWindowActivated);
}

Looking back at OnSettingsRequested, each command has a string identifier. When a command is invoked, that string identifier is returned through the IUICommand instance in the Id property. Based on that, I decided which popups to open. Since each has a similar structure, I am going to cover the implementation of just one—Music & SFX.

Here is what the end result looks like:

The panel on the left is a Popup, with two ToggleButton controls used to enable or disable generic music and sound effects. There are also two Slider controls that are used to adjust the volume. The XAML for the above layout looks like this:

<Popup HorizontalAlignment="Right" IsLightDismissEnabled="True" x:Name="stkMusicSfx" >
    <Grid Background="Black" x:Name="grdSubMusicSfx"  Width="346">
        <Grid.Transitions>
            <TransitionCollection>
                <RepositionThemeTransition />
            </TransitionCollection>
        </Grid.Transitions>

        <Grid.RowDefinitions>
            <RowDefinition Height="120"></RowDefinition>
            <RowDefinition Height="*"></RowDefinition>
        </Grid.RowDefinitions>

        <StackPanel Grid.Row="0" Orientation="Horizontal" Margin="24,12,0,0" >
            <Button Margin="0" VerticalAlignment="Center" x:Name="dismissAudioSettings" Click="dismissAudioSettings_Click" Style="{StaticResource BackButtonStyle}"></Button>
            <TextBlock Margin="12,0,0,12" Height="Auto" VerticalAlignment="Center" Text="Music &amp; SFX" Style="{StaticResource SubheaderTextStyle}"></TextBlock>
        </StackPanel>

        <StackPanel Grid.Row="1" Margin="24,24,0,0">
            <StackPanel>
                <TextBlock Text="Music" Style="{StaticResource BodyTextStyle}"></TextBlock>
                <TextBlock  Width="346" Text="This includes the theme track and level background music." Style="{StaticResource CaptionTextStyle}" TextWrapping="Wrap" Margin="0,12,12,12" ></TextBlock>
                <ToggleSwitch x:Name="tglMusic" Toggled="tglMusic_Toggled" IsOn="{Binding ElementName=XAMLPage,Path=MusicEnabled}" Margin="-6,0,0,0"></ToggleSwitch>
            </StackPanel>

            <StackPanel Margin="0,24,0,0">
                <TextBlock Text="Music Volume" Style="{StaticResource BodyTextStyle}"></TextBlock>
                <Slider x:Name="sldMusicVolume" ValueChanged="sldMusicVolume_ValueChanged" Value="{Binding ElementName=XAMLPage,Path=MusicVolume, Mode=TwoWay}" Minimum="0" Maximum="100" Margin="0,0,12,0"></Slider>
            </StackPanel>

            <StackPanel Margin="0,24,0,0">
                <TextBlock Text="Sound Effects" Style="{StaticResource BodyTextStyle}"></TextBlock>
                <TextBlock Width="346" Text="Includes sounds played during the game (e.g. explosions)." Style="{StaticResource CaptionTextStyle}" TextWrapping="Wrap" Margin="0,12,12,12" ></TextBlock>
                <ToggleSwitch x:Name="tglSFX" Toggled="tglSFX_Toggled" IsOn="{Binding ElementName=XAMLPage,Path=SFXEnabled}" Margin="-6,0,0,0"></ToggleSwitch>
            </StackPanel>

            <StackPanel Margin="0,24,0,0">
                <TextBlock Text="SFX Volume" Style="{StaticResource BodyTextStyle}"></TextBlock>
                <Slider x:Name="sldSFXVolume" ValueChanged="sldSFXVolume_ValueChanged" Value="{Binding ElementName=XAMLPage,Path=SFXVolume, Mode=TwoWay}" Minimum="0" Maximum="100" Margin="0,0,12,0"></Slider>
            </StackPanel>

        </StackPanel>

    </Grid>
</Popup>

For every Popup instance used for settings, make sure that IsLightDismissEnabled is set to true. This allows the user to dismiss the panel with a touch outside its boundaries, just like the stock system panels. Other than that, you are working with the standard XAML control set and can include virtually anything in your settings.

Notice, that the switches and sliders are bound to internal properties, such as SFXEnabled and MusicEnabled, that perform the binding via dependency property references:

DependencyProperty^ DirectXPage::_musicEnabled = DependencyProperty::Register("MusicEnabled", 
bool::typeid, DirectXPage::typeid, nullptr);
DependencyProperty^ DirectXPage::_sfxEnabled = DependencyProperty::Register("SFXEnabled", 
bool::typeid, DirectXPage::typeid, nullptr);

The properties themselves are declared in the DirectXPage header file:

static property DependencyProperty^ SFXVolumeProperty
{
    DependencyProperty^ get() { return _sfxVolume; }
}
property int SFXVolume
{
    int get() { return (int)GetValue(SFXVolumeProperty); }
    void set(int value) 
    { 
        SetValue(SFXVolumeProperty, value);
    }
}

static property DependencyProperty^ MusicVolumeProperty
{
    DependencyProperty^ get() { return _musicVolume; }
}
property int MusicVolume
{
    int get() { return (int)GetValue(MusicVolumeProperty); }
    void set(int value) 
    { 
        SetValue(MusicVolumeProperty, value);
    }
}

Let’s take a quick look at how settings are stored. I have a class called SettingsHelper that allows me to save, read, and check if specific settings exist. Here is the implementation:

#include "pch.h"
#include "SettingsHelper.h"

using namespace Windows::Storage;
using namespace Coding4Fun::FallFury::Helpers;

SettingsHelper::SettingsHelper(void)
{
}

void SettingsHelper::Save(Platform::String^ key, Platform::Object^ value)
{
    ApplicationDataContainer^ localSettings = ApplicationData::Current->LocalSettings;
    auto values = localSettings->Values;

    values->Insert(key, value);
}

Platform::Object^ SettingsHelper::Read(Platform::String^ key)
{
    ApplicationDataContainer^ localSettings = ApplicationData::Current->LocalSettings;
    auto values = localSettings->Values;

    return values->Lookup(key);
}

bool SettingsHelper::Exists(Platform::String^ key)
{
    ApplicationDataContainer^ localSettings = ApplicationData::Current->LocalSettings;
    auto values = localSettings->Values;

    return values->HasKey(key);
}

It is clear that storage and retrieval heavily relies on the ApplicationDataContainer class, the container class for local settings that eliminates the need for the developer to create his own setting files, instead delegating this task to the OS and utilizing a centralized storage for all Windows Store applications.

A typical scenario that utilizes the class above is executed when the toggle that manages the sound effects is switched:

void DirectXPage::tglSFX_Toggled(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
    SettingsHelper::Save("sfxEnabled", tglSFX->IsOn);
    SFXEnabled = tglSFX->IsOn;
    AudioManager::IsSFXStarted = SFXEnabled;

    if (SFXEnabled)
    {
        AudioManager::AudioEngineInstance.StartSFX();
    }
    else
    {
        AudioManager::AudioEngineInstance.SuspendSFX();
    }
}

The Boolean value above will be automatically serialized and stored. The files will be located at C:\Users\YOUR_USER_NAME\AppData\Local\Packages\PACKAGE_ID\Settings\settings.dat:

Conclusion

Implementing sharing through the OS channel in Windows 8 is extremely easy seeing as the developer does not necessarily have to worry about connecting the app to third-party API endpoints. Instead, the user controls the sharing, allowing flexibility of choice without requiring a major addition to the existing code base. It’s hard to predict which services might appear, and modifying the app to support each one of them would be next to impossible otherwise.

You can read more about settings in Windows Store applications here.

During gameplay there are scenarios during which users need to be visually notified that something has happened, such as a collision with an obstacle or an enemy shell. One way to do this is by having explosion or item breaking simulation, which brings us to the next large component in FallFury—the sprite-based particle system. It doesn’t offer as much power as a full-fledged particle system would, but it allows for effects that fit well within the overall theme and layout of the game.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-9-Particle-System .  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

The Core

ParticleSystem is the dedicated folder in the project that contains everything needed to render multiple textures at once and displace them to create the desired effect:

A single particle carries information regarding its size, position, velocity, color shading, rotation, circular velocity, and scale. As with any other rendered entity, it has a bounding box that can be used to detect its intersection with other elements on the screen. In FallFury, this functionality is not used.

Its structure is as follows:

#pragma once
#include "pch.h"
struct Particle
{
    Particle(float2 size);
    Particle(float2 size, float4 shading);
    float2 Size;
    float2 Position;
    float2 Velocity;
    float4 Shading;
    float Rotation;
    float RotationVelocity;
    float Scale;
    bool IsWithinScreenBoundaries(float x, float y, Windows::Foundation::Rect screenBounds);
    Windows::Foundation::Rect GetBoundingBox();
};

The Particle class also happens to have two constructors—one that sets the particle to have the default shading, effectively removing the effect, and one where shading is dynamic. Note that a particle on its own doesn’t do much—it neither carries the associated texture nor has an internal loop that can be used in any given application part to display it.

The next core class is ParticleSet. It is used as a container for all the particles associated with a specific effect. For example, if I want to create flying stuffing when the bear hits an obstacle, I create a new ParticleSet instance and define the necessary particle properties:

• Lifespan – a particle set does not constantly animate. It displays the particles for a limited amount of time, and displaces them by the given velocity values, and then self-destructs.
• Texture – all particles in a ParticleSet have the same texture. Going back to the stuffing example, there is a single PNG file used to render multiple variable-sized particles on collision.
• IsAlive – this is the flag that shows whether the particle set should be rendered in the first place. If it is set to false then, regardless of the conditions, this ParticleSet instance is ignored.
• ShouldScale – this flag determines whether particles will automatically increase their scale as they are being displaced, creating the effect of a particle approaching the screen. This effect is applied to each particle in the set.

The container class is used to update the particles through the Update function:

void ParticleSet::Update(float timeDelta)
{
    float quat = _lifespan / 0.016f;
    float decrement = 1.0f / quat;
    
    if (_totalTime <= _lifespan && _isAlive)
    {
        _totalTime += timeDelta;
        
        for (auto particle = _particles.begin(); particle != _particles.end(); particle++)
        {
            if (_shouldScale)
                particle->Scale += 0.2f;
            
            particle->Shading.a -= decrement;
            particle->Position = float2(particle->Position.x + particle->Velocity.x,
                            particle->Position.y + particle->Velocity.y);
            
            if (!_shouldScale)
                particle->Rotation += particle->RotationVelocity;
        }
    }
    else
    {
        _totalTime = 0.0f;
        _isAlive = false;
    }
}

As it relies on the _isAlive flag, the Update loop is only used when the particle displacement is activated via the Activate function:

void ParticleSet::Activate(float2 position, float2 velocity, bool randomize, bool scale)
{
    for (auto particle = _particles.begin(); particle != _particles.end(); particle++)
    {
        particle->Position = position;

        if (randomize)
            particle->Velocity = float2(RandFloat(-5.0f,5.0f), RandFloat(-5.0f, 5.0f));
        else
            particle->Velocity = float2(velocity.x + RandFloat(-0.6f, 0.6f), velocity.y + RandFloat(-0.6f, 0.6f));;
    }

    _shouldScale = scale;
    _isAlive = true;
}

When a set is activated, several user-defined parameters come into play. The position is set no matter what and is used to create the source point from which the particles start appearing. The velocity, on the other hand, can be randomized between the values of -5 and 5 pixels per update loop, on both the X-axis and the Y-axis. If randomized, large amount of particles will create an explosion that starts from the center point and expands towards all quadrants. When the velocity is not randomized, it creates a triangular expansion grid on which particles deviate from the center point in one of the given directions:

When it’s time to render the particles, the sprite batch associated with the current game screen is used to pass a texture for each particle registered in the set:

void ParticleSet::Render(SpriteBatch ^spriteBatch)
{
    for (auto particle = _particles.begin(); particle != _particles.end(); particle++)
        {
        if (GamePlayScreen::Manager->IsWithinScreenBoundaries(particle->Position))
                    spriteBatch->Draw(_texture.Get(), particle->Position, PositionUnits::DIPs,
                    particle->Size * particle->Scale, SizeUnits::Pixels, particle->Shading, particle->Rotation);
        }
}

Although there is no flag check inside the Render method that would make sure that the set is alive, this can be done outside of it by calling IsAlive, which will return the flag value:

bool ParticleSet::IsAlive()
{
    return _isAlive;
}

Let’s now take a look at the class that managed the particle flow—ParticleCore.

The Particle Manager

ParticleCore is the class that manages internal particle sets, and is also the proxy for set activation, update, and rendering. Here is its structure:

#pragma once
#include "pch.h"
#include "ParticleSet.h"
#include <list>
#include <map>

class ParticleCore
{
    public:
    ParticleCore();
    ParticleCore(Coding4Fun::FallFury::Screens::GameScreenBase^);
    virtual ~ParticleCore();
    
    void CreatePreCachedParticleSets();
    void ActivateSet(Platform::String^, float2);
    void ActivateSet(Platform::String^, float2, float2);
    void ActivateSet(Platform::String^, float2, bool);
    void ActivateSet(Platform::String^, float2, float2, bool);
    void ActivateSet(Platform::String^, float2, float2, bool, bool scale);
    void Update(float);
    void Render();
    
    private:
        std::list<ParticleSet>                                                    _renderParticleSets;
        std::map<Platform::String^, ParticleSet*>                                _particleSetCache;
        std::map<Platform::String^, Microsoft::WRL::ComPtr<ID3D11Texture2D>>    _textureCache;
        Coding4Fun::FallFury::Screens::GameScreenBase^                            _screenBase;
};

As previously mentioned, set activation can be done with some omitted parameters inferred by the system, such as randomization of velocity or particle scaling, which is the reason why you see multiple overloads for ActivateSet.

ParticleCore is also the container for pre-defined sets that have specific textures and properties that are dumped in the particle set cache (internal _particleSetCache). The cache is reusable and even though sets can be activated and destroyed, the cache remains intact for the duration of the game unless explicitly reset or modified. The texture cache is an addition to the particle set cache and is used as a helper container to temporarily store the textures used for individual particles.

Taking a look under the hood at the CreatePreCachedParticleSets function, you can see multiple sets that can be used in the game, each with different properties. Here is a snippet that shows how the bear stuffing explosion set is created:

auto smallExplosionSet = new ParticleSet(_textureCache["Stuffing"], LIFESPAN);
for (int i = 0; i < 20; i++)
{
    float size = RandFloat(50.0f, 100.0f);
    Particle particle(float2(size, size));
    smallExplosionSet->AddParticle(particle);
}

Once all the particles are in place for that specific set, it is added to the global particle set cache:

_particleSetCache["SmallExplosion"] = smallExplosionSet;

The particle set cache is not explicitly used to render anything on the screen. Rather, that task is delegated to the rendering cache. When a set is activated, the cache is inspected for the given key, its Activate function is called, marking it as alive, and the set itself is pushed on the rendering stack:

void ParticleCore::ActivateSet(Platform::String^ name, float2 position, float2 velocity, bool randomize, bool scale)
{
    ParticleSet set = ParticleSet(*_particleSetCache[name]);
    set.Activate(position, velocity, randomize, scale);
    _renderParticleSets.push_back(set);
}

The Render loop takes care of invoking the proper SpriteBatch drawing functions for each set that is in that stack:

void ParticleCore::Render()
{
    for (auto set = _renderParticleSets.begin(); set != _renderParticleSets.end(); ++set)
    {
        if ((*set).IsAlive())
        {
            (*set).Render(_screenBase->CurrentSpriteBatch);
        }
    }
}

Notice that, as previously mentioned, the set does not perform the life check on itself when rendering. Instead, the manager class performs this action. The same applies to the Update loop:

void ParticleCore::Update(float timeDelta)
{
    for (auto set = _renderParticleSets.begin(); set != _renderParticleSets.end();)
    {
        if ((*set).IsAlive())
        {
            (*set).Update(timeDelta);
            ++set;
        }
        else
        {
            set = _renderParticleSets.erase(set);
        }
    }
}

The textures for each set are individually loaded in the CreatePreCachedParticleSets. Each instance is internally pushed into the cache and also added to the sprite batch associated with the current game screen, where ParticleCore is used:

Loader->LoadTexture("DDS\\stuffing.dds", &_textureCache["Stuffing"], nullptr);
_screenBase->CurrentSpriteBatch->AddTexture(_textureCache["Stuffing"].Get());

Once everything is loaded, the ParticleCore is ready to go and you can use as many particles as necessary in any part of the application. In GamePlayScreen, particle sets are activated in many cases. For example, if the bear dies:

void GamePlayScreen::CheckBearHealth()
{
    if (GameBear->CurrentHealth <= 0)
    {
        m_particleSystem.ActivateSet("Buttons",GameBear->Position, true);
        GameBear->Kill();
        StopBackground();
    }
}

Conclusion

Implementing a sprite-based particle system is not complicated, but it requires depending on a number of assumptions. For example, when a particle set is created, you might consider the fact that some hardware can handle drawing only a given number of sprites at the same time. If a particle set is rendered on a desktop machine, there is no guarantee that the same set will successfully render on an ARM device. Therefore, plan accordingly. For each particle set, create a lifespan that fits the scenario without wasting resources on rendering unnecessary particles. As an additional failsafe, you might want to disable specific particle set types when a Direct3D feature level below 10.0 is detected.

During the gameplay multiple entities interact with each other to make the gaming experience what it is. The bear collides with obstacles and collects buttons, monsters shoot shells that can fly off-screen or hit the bear—all this is possible with the help of the basic collision detection techniques that are implemented in FallFury.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-8-Element-Interaction . For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

Buttons

Buttons are bonus-boosters that can be placed by the level designer anywhere on the screen in game mode. These are relatively small entities, which are displaced vertically with each cycle of the Update loop and move in the opposite direction, but with the same velocity, as the main character.

Looking at the Update function in the GamePlayScreen class, you will notice this call:

UpdateButtons();

UpdateButtons can be considered the button manager function responsible for removing the collected buttons from the rendering stack, counting them, and checking for a button collision when the bear is in close proximity. The implementation looks like this:

void GamePlayScreen::UpdateButtons()
{
    Windows::Foundation::Rect livingEntityBoundingBox = GameBear->GetBoundingBox();
    for (auto button = m_buttons.begin(); button != m_buttons.end();)
    {
        (*button)->Position.x = (*button)->PixelDiff + LoBoundX;
        (*button)->Position.y -= GameBear->Velocity.y;
        if (Geometry::IsInProximity(GameBear->Position,(*button)->Position, 100))
        {
            Windows::Foundation::Rect obstacleRect = (*button)->GetBoundingBox();
            if (livingEntityBoundingBox.IntersectsWith(obstacleRect))
            {
                AudioManager::AudioEngineInstance.StopSoundEffect(Coin);
                AudioManager::AudioEngineInstance.PlaySoundEffect(Coin);
                m_particleSystem.ActivateSet("Sparkle", (*button)->Position,float2(RandFloat(-6.0f,6.0f),RandFloat(-10.0f, -5.0f)));
                StaticDataHelper::ButtonsCollected++;
                button = m_buttons.erase(button);
            }
            else
            ++button;
        }
        else
        {
            ++button;
        }
    }
}

For performance reasons, FallFury supports composite bounding box creation as well as simple box creation. As mentioned earlier in the series, the main character is not composed of a single texture, but rather multiple sprites that are cross-positioned to create a single visual entity. To give you a better idea of what composite vs. simple boxing looks like, take a look at the images below:

The image on the left shows how each part of the bear has its own bounding box, and each will be used for collision checking. In the image on the right, the bear has a single bounding box, creating minor potential gaps, but gaining performance.

Going back to UpdateButtons, once the bounding box is obtained, I iterate through the button collection and make sure that each item is located in the proper space:

(*button)->Position.x = (*button)->PixelDiff + LoBoundX;
(*button)->Position.y -= GameBear->Velocity.y;

The constant position checks are necessary because FallFury supports dynamic orientation changes. When the user switches from portrait to landscape mode and vice-versa, rendered elements on the screen are not automatically repositioned. Setting the X position is easy as long as there is a fixed button margin (from the left side of the screen: LoBoundX) and adding it to the current LoBoundX value results in a proper X location. There is no need to do the same check on the Y-axis because the level length remains the same regardless of the current screen orientation. The adjustment made relative the Y position is bound to the bear velocity. If the bear moves slower, buttons will also scroll slower.

Given that all buttons are properly positioned, a proximity check is performed on each button passed through the loop. If the bear position is at least 100 pixels away from the current button, the corresponding bounding box is obtained and an intersect check is performed. In simple boxing mode, this is done via Windows::Foundation::Rect::IntersectsWith:

If a collision occurs, the appropriate sound effect is played and a particle set is activated to create a visual notification of the action. After the button counter is incremented, the button is removed from the local collection, effectively being removed from the rendering stack.

Power-ups

As the bear flies towards the end of the level, it might encounter bonuses to improve its ability to fight incoming enemies or protect from damage caused by enemy ammo or obstacles. The process behind displaying power-ups on the screen and determining whether there was a collision with the main character is similar to UpdateButtons.

The core function for this task is UpdatePowerups:

void GamePlayScreen::UpdatePowerups(float timeDelta)
{
    if (m_powerups.size() > 0)
    {
        for (auto powerup = m_powerups.begin(); powerup != m_powerups.end(); powerup++)
        {
            (*powerup)->Update(timeDelta);
            (*powerup)->Position.x = (*powerup)->PixelDiff + LoBoundX;
            (*powerup)->Position.y -= GameBear->Velocity.y;
        }
    }
    CheckForCollisionWithPowerups();
}

One difference you probably noticed in the snippet above is the fact that the collision check is now done through a separate function—CheckForCollisionWithPowerups:

void GamePlayScreen::CheckForCollisionWithPowerups()
{
    Powerup^ currentPowerup;
    Windows::Foundation::Rect livingEntityBoundingBox = GameBear->GetBoundingBox();
    for (auto powerup = m_powerups.begin(); powerup != m_powerups.end();)
    {
        currentPowerup = (*powerup);
        if (Geometry::IsInProximity(GameBear->Position,currentPowerup->Position, 100))
        {
            Windows::Foundation::Rect obstacleRect = currentPowerup->GetBoundingBox();
            if (livingEntityBoundingBox.IntersectsWith(obstacleRect))
            {
                AudioManager::AudioEngineInstance.PlaySoundEffect(GenericPowerup);
                GameBear->PickupPowerup(currentPowerup, &m_particleSystem);
                powerup = m_powerups.erase(powerup);
            }
            else
            ++powerup;
        }
        else
        {
            ++powerup;
        }
    }
}

If an intersection is detected between the boxed bear and the power-up texture, the current power-up is passed to the Bear instance and the appropriate type of action is selected:

void Bear::PickupPowerup(Powerup^ powerup, ParticleCore* ParticleSystem)
{
    switch (powerup->Type)
    {
        case PowerupType::PARACHUTE:
        {
            m_previousVelocity = Velocity.y;
            SetParachute(powerup->Lifespan);
            Velocity.y -= powerup->Effect;
            ParticleSystem->ActivateSet("ScalableParachute", Position, 0.0f, false, true);
            break;
        }
        case PowerupType::HEALTH:
        {
            CurrentHealth = MaxHealth;
            ParticleSystem->ActivateSet("ScalableHeart", Position, 0.0f, false, true);
            break;
        }
        case PowerupType::BUBBLE:
        {
            if (IsHelmetEnabled)
            {
                IsHelmetEnabled = false;
                DamageDivider = 1.0f;
            }
            else
            {
                DamageDivider = powerup->Effect;
            }
            IsBubbleEnabled = true;
            m_maxBubbleCounter = powerup->Lifespan;
            ParticleSystem->ActivateSet("ScalableBubble", Position, 0.0f, false, true);
            break;
        }
        // [...]
        case PowerupType::BOOMERANG:
        {
            m_weaponType = powerup->Type;
            m_weaponTexture = m_boomerangTexture;
            CurrentDamage = powerup->Effect;
            m_weaponSize = float2(225.0f, 205.0f) * 0.5f;
            ParticleSystem->ActivateSet("ScalableBoomerang", Position, 0.0f, false, true);
            break;
        }
    }
}

Depending on the power-up, textures are added to the bear model and later passed to the rendering stack (if the power-up type is PARACHUTE), some textures and capabilities are replaced (BOOMERANG), or the bear capabilities are temporarily modified (BUBBLE):

If one of the temporary power-ups is enabled n the Update loop, dedicated timers ensure that ability enhancement does not last longer than necessary. As an example, here is the snippet that controls the bubble:

if (IsBubbleEnabled)
{
    m_currentBubbleCounter += timeDelta;
    if (m_currentBubbleCounter > m_maxBubbleCounter)
    {
        IsBubbleEnabled = false;
        DamageDivider = 1.0f;
        m_currentBubbleCounter = 0.0f;
    }
}

Ammo Collisions

There are also objects that direct ammo at either the enemy or the bear. After release, each shell follows a linear path towards the target, and while the user directs the shells that originate from the bear, those released by enemy entities automatically target the bear. In this case, the ammo needs to collide with an object to either damage or kill it. When a shell is released, it is added to the general ammo collection that is later updated internally:

void GamePlayScreen::UpdateAmmo(float timeDelta)
{
    for (auto shell = m_ammoCollection.begin(); shell != m_ammoCollection.end(); shell++)
    {
        (*shell)->Update(timeDelta, &m_particleSystem);
    }
}

At this point, the rendering system does not differentiate between friendly and enemy ammo—all it knows is that each item in the collection must have a new position when a new frame is rendered. The CheckForCollisionsWithAmmo function checks for ammo collisions:

void GamePlayScreen::CheckForCollisionWithAmmo(LivingEntity^ entity)
{
    if (entity != nullptr)
    {
        Windows::Foundation::Rect livingEntityBoundingBox = entity->GetBoundingBox();
        if (entity->IsFriendly)
        {
            for (auto ammo = m_ammoCollection.begin(); ammo != m_ammoCollection.end();)
            {
                if (!(*ammo)->IsFriendly)
                {
                    Windows::Foundation::Rect ammoBoundingBox = (*ammo)->GetBoundingBox();
                    if (livingEntityBoundingBox.IntersectsWith(ammoBoundingBox))
                    {
                        m_particleSystem.ActivateSet("SmallExplosion",entity->Position, true);
                        entity->InflictDamage((*ammo)->HealthDamage);
                        GameBear->RedShade();
                        AudioManager::AudioEngineInstance.PlaySoundEffect(OuchA);
                        AudioManager::AudioEngineInstance.PlaySoundEffect(HardSoftCollision);
                        CheckBearHealth();
                        ammo = m_ammoCollection.erase(ammo);
                    }
                    else
                    {
                        ++ammo;
                    }
                }
                else
                {
                    ++ammo;
                }
            }
        }
        else
        {
            for (auto ammo = m_ammoCollection.begin(); ammo != m_ammoCollection.end();)
            {
                if ((*ammo)->IsFriendly)
                {
                    Windows::Foundation::Rect ammoBoundingBox = (*ammo)->GetBoundingBox();
                    if (livingEntityBoundingBox.IntersectsWith(ammoBoundingBox))
                    { 
                        Monster^ monster = ((Monster^)entity);
                        if (!monster->IsDead && monster->IsActive)
                        {
                            m_particleSystem.ActivateSet("SmallExplosion", entity->Position, true);
                            entity->InflictDamage((*ammo)->HealthDamage);
                            monster->RedShade();
                            monster->CheckIfAlive();
                            AudioManager::AudioEngineInstance.PlaySoundEffect(SharpSoftCollision);
                        }
                        ammo = m_ammoCollection.erase(ammo);
                    }
                    else
                    {
                        ++ammo;
                    }
                }
                else
                {
                    ++ammo;
                }
            }
        }
    }
}

When the function is called, it is usually run against an entity that is present on the screen, such as the main character. Regardless of whether the enemy or the friendly character fired the shot, the shot cannot inflict damage to its source, and that’s why the function implements the ammo-to-entity crosscheck. If the ammo collides with any shells intersecting the entity bounding box, a collision is counted and health verification is performed to ensure that the character is still alive and that the game should continue. The bear’s health is checked via CheckBarHealth:

void GamePlayScreen::CheckBearHealth()
{
    if (GameBear->CurrentHealth <= 0)
    {
        m_particleSystem.ActivateSet("Buttons",GameBear->Position, true);
        GameBear->Kill();
        StopBackground();
    }
}

That said, not all ammo will collide with entities on the screen. Some of it will go out-of-bounds, and without an explicit cleanup process in place out-of-bounds ammo is constantly re-rendered even though the end user has no way of seeing it. To avoid this, there is a helper function—CheckForOutOfBoundsAmmo:

void GamePlayScreen::CheckForOutOfBoundsAmmo()
{
    for (auto l_Iter = m_ammoCollection.begin(); l_Iter != m_ammoCollection.end(); /* nothing here */ )
    {
        if (!GamePlayScreen::Manager->IsWithinScreenBoundaries((*l_Iter)->Position))
        {
            l_Iter = m_ammoCollection.erase(l_Iter);
        }
        else
        {
            ++l_Iter;
        }
    }
}

If any shell flies outside the screen bounding box, its instance is erased from the collection and the renderer no longer worries about allocating memory for an irrelevant item. To give you an idea of how that happens, here is a snippet that shows how the RenderScreen function handles the current ammo set:

if (!m_ammoCollection.empty())
{
    for (auto shell = m_ammoCollection.begin(); shell != m_ammoCollection.end(); shell++)
    {
        if (!(*shell)->IsFriendly)
        {
            (*shell)->Render();
        }
        else
        {
            GameBear->RenderShell((*shell)->Position, (*shell)->Rotation);
        }
    }
}

Conclusion

Element interaction is a core part of the FallFury experience. Separate handlers are implemented for each of them to ensure maximum flexibility when it comes to adding or removing components without breaking major parts of the code-base. Handling is mainly accomplished in the Update loop by iterating through registered entity sets, such as ammo, and verifying whether an action should be taken. Be cautious when implementing this kind of scenario with large entities and data sets—having multiple loops running simultaneously might tax machine performance, especially on low-power configurations such as ARM.

FallFury relies on a lot of dynamic content. As you already aware of how SpriteBatch is invoked inside the FallFury rendering stack, this article focuses on how dynamic activities are handled on existing textures and entities. If you need a quick look at what was already covered, refer to Part 3 of the series.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-7-Animations . For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

Menu Screen

The first animated element shown in the menu screen is the bear, which is positioned in the top half of the viewport. Notice that the bear moves its paws as well as moving across the screen:

The bear is implemented in the GameBear class and is the normal playable entity that is invincible when animated outside the scope of the gameplay screen. Its full body image is composed of four textures:

Microsoft::WRL::ComPtr<ID3D11Texture2D>        m_head;
Microsoft::WRL::ComPtr<ID3D11Texture2D>        m_leftPaw;
Microsoft::WRL::ComPtr<ID3D11Texture2D>        m_rightPaw;

Microsoft::WRL::ComPtr<ID3D11Texture2D>        m_body // Exposed through LivingEntity;

Each of these textures is internally dependent on the coupled float rotation and position values passed to the sprite batch in the host container (the parent screen):

HostContainer->CurrentSpriteBatch->Draw(
    m_rightPaw.Get(),
    m_rightPawPosition,
    PositionUnits::DIPs,
    float2(522.0f, 141.0f) * Scale,
    SizeUnits::Pixels,
    m_shading,
    m_rightPawRotation - 0.5f);

HostContainer->CurrentSpriteBatch->Draw(
    m_body.Get(),
    Position,
    PositionUnits::DIPs,
    float2(400.0f, 400.0f) * Scale,
    SizeUnits::Pixels,
    m_shading,
    Rotation);

HostContainer->CurrentSpriteBatch->Draw(
    m_leftPaw.Get(),
    m_leftPawPosition,
    PositionUnits::DIPs,
    float2(522.0f, 141.0f) * Scale,
    SizeUnits::Pixels,
    m_shading,
    m_leftPawRotation + 0.5f);

Let’s take a look at how the position and rotation values are modified. All item animations are performed with the help of timers set to brief intervals in which the values are cycled through two value exchange operations. Here is a snippet taken from inside the Update method in the GameBear class that is responsible for bear arm movement:

if (m_armRotationTimer < 0.6f)
{
    m_rightPawRotation -= 0.005f;
    m_leftPawRotation += 0.005f;
}
else if (m_armRotationTimer > 0.6f && m_armRotationTimer < 1.2f)
{
    m_rightPawRotation += 0.005f;
    m_leftPawRotation -= 0.005f;
}
else
{
    m_rightPawRotation = 0.0f;
    m_leftPawRotation = 0.0f;
    m_armRotationTimer = 0.0f;
}

m_armRotationTimer is a float value that is initially set to 0.0f. In the Update loop and increments each iteration by the value of timeDelta, which represents the time difference between two loop cycles. As this value is less than 600 milliseconds (0.6 seconds), the right paw rotation is incremented and the left paw rotation decremented. The difference in the value adjustment direction is caused by the fact that one paw is rotated clockwise and the other is rotated counterclockwise. Once the timer tracks a value above 600 milliseconds but below than 1200 milliseconds, the process reverses and the paws rotate in the opposite direction. After 1.2 seconds, the timer resets, as does the rotation.

Since this rotation is automated, GameBear->Update is called in the menu screen:

m_showBear->Update(timeTotal, timeDelta, float2(Manager->m_windowBounds.Width / 2, Manager->m_windowBounds.Height / 2));

Outside the context of the bear update cycle, there is a similar timed mechanism used to randomly move the bear across the screen:

if (m_positionYAdj == 0.0f)
{
    m_positionYAdj = RandFloat(0.1f, 1.2f);
    m_positionXAdj = RandFloat(-1.0f, 1.0f);
}

if (m_positionTimer < 4.0f)
{
    m_showBear->Position.x += m_positionXAdj;
    m_showBear->Position.y += m_positionYAdj;
    m_showBear->Rotation += 0.001f;
    m_showBear->Scale += 0.0008f;
    
    m_showMonster->Scale += 0.002f;
}
else if (m_positionTimer > 4.0f && m_positionTimer < 8.0f)
{
    m_showBear->Position.x -= m_positionXAdj;
    m_showBear->Position.y -= m_positionYAdj;
    m_showBear->Rotation -= 0.001f;
    m_showBear->Scale -= 0.0008f;
}
else
{
    m_positionYAdj = 0.0f;
    m_positionTimer = 0.0f;
}

The X and Y adjustments are randomly generated and for the duration of a single timer cycle (in this case, 4 seconds) the bear’s horizontal and vertical positions are adjusted using those values. The rotation and scale are minimally adjusted to create a 3D motion effect. Because the displacement is minimal, the bear is always visible and does not move much outside the viewport.

There is also a flying monster animation in the main menu screen. Monster creation happens on top of the same instance that is replaced when an initial monster flies out of bounds:

m_showMonster->Position.y -= m_showMonster->Velocity.y;
if (m_showMonster->Position.y < -m_showMonster->Size.y)
{
    CreateNewMonster();
}

When a new monster is created, a random monster type is selected and its position on the X axis is randomized. The Y position is set to be right under the bottom screen boundary:

void MenuScreen::CreateNewMonster()
{
    m_showMonster = ref new Monster(this, (MonsterType)(rand() % (int)MonsterType::MT_CANDYLAND_E), true);
    m_showMonster->Scale = 0.3f;
    m_showMonster->Velocity.y = 1.0f;
    m_showMonster->Load();
    m_showMonster->Position = float2(RandFloat(LoBoundX, HiBoundX), Manager->m_windowBounds.Height + m_showMonster->Size.y * m_showMonster->Scale);
}

Monster scaling is done on the same timed loop as the bear. The results look like this:

Gameplay Screen

Bear

The gameplay screen carries the most animations in FallFury, including animations related to ammo displacement, monster movement paths, power-up animations, and secondary game character animations that are triggered in special cases such as character death.

Let’s start with character entrance. When the game begins, the teddy bear falls into the screen and stops at a specific point close to the top boundary of the gameplay screen. Once that transition is complete, the bear is no longer vertically displaced:

if ((GameBear->Position.y / HiBoundY) < 0.19f)
{
    GameBear->Position.y += GameBear->Velocity.y * (3.2f);
}

If the limit is not hit, the original bear velocity is multiplied by a fixed value, after which the condition is ignored for the rest of the gameplay.

Let’s now take a look at what happens when an enemy shell kills the bear. Generally, when the main character is killed, there is not much sense in maintaining other in-game activities. In FallFury, a killed bear results in a time freeze—the fall stops and the monsters are no longer shooting or moving. Not only that, but the bear is also flipped on its back:

In the Update loop, the position for the paws and the head are adjusted for the new body texture layout:

if (IsDead)
{
    if (m_armRotationTimer < 1.0f)
    {
        m_rightPawRotation += 0.001f;
        m_leftPawRotation -= 0.001f;
    }
    else if (m_armRotationTimer > 1.0f && m_armRotationTimer < 2.0f)
    {
        m_rightPawRotation -= 0.001f;
        m_leftPawRotation += 0.001f;
    }
    else
    {
        m_rightPawRotation = 0.0f;
        m_leftPawRotation = 0.0f;
        m_armRotationTimer = 0.0f;
    }

    m_rightPawPosition = Position + float2(40.0f, -50.0f) * Scale;
    m_leftPawPosition = Position + float2(10.0f, 150.0f) * Scale;
    m_headPosition = (Position - float2(-160.0f, 0.0f) * Scale);
}

The proper textures are assigned via the Kill method:

void Bear::Kill()
{
    IsDead = true;
    Rotation = -1.0f;
    m_head = m_deadHead;
    m_body = m_deadBody;
    m_leftPaw = m_deadLeftArm;
    m_rightPaw = m_deadRightArm;
}

The bear will continue falling as long as StopBackground in GamePlayScreen is called:

void GamePlayScreen::StopBackground()
{
    m_isBackgroundMoving = false;
}

This will cause the internal state check to fail in the Update loop, sending the bear off screen limits. Once the bear completes the fall, the state is set to GS_GAME_OVER:

if (!m_isBackgroundMoving)
{
    if (GameBear->Position.y > m_screenSize.y)
    {
        Manager->CurrentGameState = GameState::GS_GAME_OVER;
    }
    else
    {
        GameBear->Position.y += GameBear->Velocity.y * 1.5f;
    }
}

Monsters

Monsters, on the other hand, are being constantly moved during the duration of the game. Their basic displacement is performed by MoveMonsters:

void GamePlayScreen::MoveMonsters(float timeTotal ,float timeDelta)
{
    for (auto monster = m_monsters.begin(); monster != m_monsters.end();)
    {
        Monster^ currentMonster = (*monster);
        if ((currentMonster->Position.y - GameBear->Position.y) < -Manager->m_renderTargetSize.Height / 2)
        {
            monster = m_monsters.erase(monster);
        }
        else
        {
            currentMonster->Velocity.y = GameBear->Velocity.y;
            currentMonster->Update(timeTotal, timeDelta, GameBear->Position, GetScreenBounds());
            CheckForCollisionWithAmmo(currentMonster);
            ++monster;
        }
    }
}

This method adjusts the monster position relative to the bear:

The zig-zag like motion is defined in the Monster class in the Update method:

float adjustment = 0.0f;
adjustment = m_goingRight ? Position.x + Velocity.x : Position.x - Velocity.x;
if (adjustment >= (HostContainer->LoBoundX + (Size.x * Scale) / 2.0f) 
&& adjustment <= (HostContainer->HiBoundX - (Size.x * Scale) / 2.0f))
{
    Position.x = adjustment;
}
else
{
    m_goingRight = !m_goingRight;
}

The snippet above determines the direction in which the enemy has to move depending on which screen boundary is hit first. While the monster is active and is visible, its vertical adjustment is performed in a timed loop, like this:

m_jumpingTimer += timeDelta;
if (m_jumpingTimer > 0.0f && m_jumpingTimer < 1.0f)
{
    Position.y -= 1.0f;
}
else if (m_jumpingTimer >= 1.0f && m_jumpingTimer < 2.0f)
{
    Position.y += 1.0f;
}
else
{
    m_jumpingTimer = 0.0f;
}

Here you can either use the Y velocity or introduce a static value. The only condition has to be a number low enough that the monster does not leave the screen, which would prevent the bear from being able to kill it. When the monster is killed, it flies out by following an arch-like path:

The “death arc” is implemented via another timer:

Position.x += Velocity.y * 1.3f;
if (m_deathArcTimer > 0.4f)
{
    Position.y += Velocity.y;
    if (Scale > 0.1f)
    Scale -= 0.01f;
}
else
{
    Position.y -= Velocity.y;
    Scale += 0.01f;
    m_deathArcTimer += timeDelta;
}

Regardless of the monster position, the horizontal displacement is positive and the entity moves to the right. For 400 milliseconds its vertical position is decreased, moving the texture up, and the scale is also adjusted to create the proximity effect. After this time interval, the monster drops out of the screen boundaries.

As previously mentioned, each monster is composed of three cycled textures, which are loaded and stored in three ID3D11Texture2D containers:

Microsoft::WRL::ComPtr<ID3D11Texture2D> m_spriteA;
Microsoft::WRL::ComPtr<ID3D11Texture2D> m_spriteB;
Microsoft::WRL::ComPtr<ID3D11Texture2D> m_spriteC;

Each of these is assigned to the main body texture container every 300 milliseconds, replacing the previously assigned asset:

m_stateChangeTimer += timeDelta;
if (m_stateChangeTimer < 0.3f)
{
    m_body = m_spriteA;
}
else if (m_stateChangeTimer > 0.3f && m_stateChangeTimer < 0.6f)
{
    m_body = m_spriteB;
}
else if (m_stateChangeTimer > 0.6f && m_stateChangeTimer < 0.9f)
{
    m_body = m_spriteC;
}
else if (m_stateChangeTimer > 0.9f)
{
    m_stateChangeTimer = 0.0f;
}

This cycle can be disabled when the monster is not active.

Ammo

There are different types of ammo used in the game, and each behaves in its own way. The stock ammo type is a plasma ball.

The default shooting behavior releases a shell when the user taps anywhere on the screen (other than the pause button area). Given the texture of the shell, when it is released the tail must be oriented towards the bear at an angle equal to the one created by the bear and the target position. To get a better idea, take a look at the images below:

In the image on the left, the player tapped at the bottom of the screen. In the one on the right, the player tapped at the right edge of the screen. The shell accordingly rotates depending on the tapped position. To get a better understanding of how the rotation is performed, imagine the XY coordinate grid with the bear located at the intersection of the axes:

Thinking back to trigonometry, notice the triangle formed by the shell and the bear origin point:

Remember also the trig concept of quadrants:

The quadrant in which the shell is located determines how the angle is calculated and the tail rotated. If the shell is in quadrant 2 or 3, calculate the rotation radians by following this algorithm:

1. Find the hypotenuse from the X and Y components of the velocity, which can be calculated by finding the difference between the bear and the position of the tap. To do this, us the well-known Pythagorean theorem:

The hypotenuse formula can be deduced from the formula above and is the square root of the sum of the velocity component squares:

2. Once calculated, it is necessary to find the sine of the target angle. The value can be obtained by dividing the Y component of the velocity by the hypotenuse.

3. Find the angle by calculating the arcsine from the resultant sine value. This will return the final angle in radians.

That said, for shells launched in quadrants 1 or 4, there is one extra step that needs to be performed. In addition to the rotation value obtained from the steps listed above, the rotation should be incremented by the radian value of a 180-degree angle minus twice the rotation value previously obtained. This ensures that the tail is correctly flipped relative to the axis origin.

In C++, the implementation is done inside the AmmoItem class. For flexibility purposes, it triggers inside the Update loop—that way, it is possible to modify the trajectory of the shell and not worry about turning it again manually after launch:

if ((Velocity.x > 0 && Velocity.y > 0) || (Velocity.x > 0 && Velocity.y <0))
{
    Rotation = CalculateRadians(Velocity);
    Rotation += CalculateRadiansFromAngle(180) - 2 * Rotation;
}
else
{
    Rotation = CalculateRadians(Velocity);
}

CalculateRadians is the method that transforms the velocity components in a rotation value. It is located in the BasicMath.h helper:

inline float CalculateRadians(float2 velocity)
{
    float hypothenuse = sqrt(velocity.x * velocity.x + velocity.y * velocity.y);
    float sine = velocity.y / hypothenuse;
    float angle = asin(sine);
    return angle;
};

There is a potential problem with the implementation above. As the user taps on different parts of the screen, the X and Y components are different, each resulting in a different hypotenuse. As the target is set, the shell flies faster the further away from the bear the user taps. To avoid this, the triangle legs should be normalized to a near-constant value:

Take a look at the ShootAtTarget function in the Bear class:

void Bear::ShootAtTarget(float2 lastTargetTrace)
{
    OnPulledTrigger(Position.x, Position.y, 
    GetVelocityLegs(lastTargetTrace).x, GetVelocityLegs(lastTargetTrace).y, 
    CurrentDamage, IsFriendly, false, HostContainer->CurrentSpriteBatch);
}

Notice that the triangle legs are not passed as a raw value, but are proxied through GetVelocityLegs, which forces the resulting vector to be produced from a constant triangle with the velocity constant at 10 pixels per iteration:

float2 LivingEntity::GetVelocityLegs(float2 lastTargetTrace)
{
    float bottomLeg = 0.0f;
    float sideLeg = (Position.y - lastTargetTrace.y) / 100.0f;
    bottomLeg = (Position.x - lastTargetTrace.x) / 100.0f;
    float requiredVelocity = 10.0f;
    float hypothenuse = sqrt(bottomLeg * bottomLeg + sideLeg * sideLeg);
    float proportionalX = 0.0f;
    float proportionalY = 0.0f;
    proportionalX = (requiredVelocity * bottomLeg) / hypothenuse;
    proportionalY = (sideLeg < 0.0f ? -1 : 1) * sqrt(requiredVelocity * requiredVelocity - proportionalX * proportionalX);
    return float2(proportionalX,proportionalY);
}

For ammo that does not have a visual rotation dependency, such as the plasma ball, simply increment the rotation to make the thrown item continuously spin:

if (Type == PowerupType::PLASMA_BALL)
{
    if ((Velocity.x > 0 && Velocity.y > 0) || (Velocity.x > 0 && Velocity.y <0))
    {
        Rotation = CalculateRadians(Velocity);
        Rotation += CalculateRadiansFromAngle(180) - 2 * Rotation;
    }
    else
    {
        Rotation = CalculateRadians(Velocity);
    }
}
else
{
    Rotation += 0.2f;
}

Conclusions

FallFury mostly relies on sprite-based animations in which there are several textures cycled through in order to create the desired dynamic effect. These are not really hard to build, given that there is a possibility to integrate them in a timed loop. Be aware, however, that with slower machines the timing might be off and the time delta value between loops might be higher. In that case the sprite cycling will not be as smooth as it should be, which is why it’s important to perform animation testing on a variety of hardware with different OS loads.

In the previous article, you learned how to build level XML files in order to create playable levels. This article discusses how the internal parser works and how XML nodes become items on the game screen.  Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-6-Rendering-Level-Elements.  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

Project Interop – The C# Parser

Thanks to classes such as XmlSerializer and XDocument, parsing XML in .NET Framework is not a complicated task. Similarly, in the WinRT world there are alternatives such as Windows::Data::Xml::Dom. That being said, using the parser skeleton in C# this project leverages the existing codebase, adapting it to the specific level reading needs.

Start by creating a new WinRT project that is the part of the existing solution. Make sure that you create a Windows Runtime Component:

There are major differences between the .NET and WinRT stacks, especially when it comes to building code that can be invoked from any potential WinRT project type, as is the case here. Make sure that the output of the newly created project is a Windows Runtime Component (WinMD file):

The XMLReader project reads much more than the level data—it also manages internal XML metadata such as user scores. This article, however, focuses only on level-related aspects of the engine.

Reader is the one core class used here. It contains the ReadXml method, which receives the file name and the type of the XML file to be read. Regardless of the name, the XML file type determines the parsing rules, the root lookup location, and the produced output. The tier (level set) and individual level data are stored internally in the application folder, and the score metadata is outside the sandbox in the application data folder:

async Task<Object> ReadXml(string fileName, XmlType type)
{
        StorageFile file = null;
        StorageFolder folder = null;
    
        if (type == XmlType.LEVEL || type == XmlType.TIERS)
        {
                folder = Windows.ApplicationModel.Package.Current.InstalledLocation;
                folder = await folder.GetFolderAsync("Levels");
        }
        else if (type == XmlType.HIGHSCORE)
        {
                folder = ApplicationData.Current.LocalFolder;
                folder = await folder.GetFolderAsync("Meta");
        }
    
        file = await folder.GetFileAsync(fileName);
    
        Object returnValue = null;
        string data;
    
        using (IRandomAccessStream readStream = await file.OpenAsync(FileAccessMode.Read))
        {
                using (Stream inStream = Task.Run(() => readStream.AsStreamForRead()).Result)
                {
                        using (StreamReader reader = new StreamReader(inStream))
                        {
                                data = reader.ReadToEnd();
                        }
                }
        }
    
        if (type == XmlType.LEVEL)
        {
                returnValue = ExtractLevelData(data);
        }
        else if (type == XmlType.HIGHSCORE)
        {
                returnValue = ExtractScoreData(data);
        }
        else if (type == XmlType.TIERS)
        {
                returnValue = ExtractTierData(data);
        }
    
        return returnValue;
}

Before the level data is extracted, FallFury needs to know about the existing tiers pointing to those levels. That’s where ExtractTierData, an internal method that accepts a raw XML string and return a TierSet instance, comes in:

public sealed class TierSet
{
    public Tier[] Tiers { get; set; }
}

A Tier class has the following structure:

public sealed class Tier
{
    public string Name { get; set; }
    public string[] LevelNames { get; set; }
    public string[] LevelFiles { get; set; }
}

I am using the most fundamental types – arrays instead of generic collections, to maximize the portability of the code. The ExtractTierData method handles the XML-to-Object transformation:

TierSet ExtractTierData(string tierString)
{
        TierSet set = new TierSet();
    
        XDocument document = XDocument.Parse(tierString);
    
        set.Tiers = new Tier[document.Root.Elements().Count()];
    
        int tierCounter = 0;
    
        foreach (XElement element in document.Root.Elements())
        {
                Tier tier = new Tier();
                tier.Name = element.Attribute("name").Value;
        
                tier.LevelFiles = new string[element.Elements("level").Count()];
                tier.LevelNames = new string[element.Elements("level").Count()];
        
                
                int count = 0;
                foreach (XElement lElement in element.Elements("level"))
                {
                        tier.LevelFiles[count] = lElement.Attribute("file").Value;
                        tier.LevelNames[count] = lElement.Attribute("name").Value;
                        count++;
                }
        
                set.Tiers[tierCounter] = tier;
                tierCounter++;
        }
    
        return set;
}

I am running a coupled array block here, utilizing one array for level names and another for file locations. This is a very basic implementation of a key-value pair that depends on code-based coupling. ExtractTierData, however, is not exposed publicly and the C++ layer of FallFury will not access it because TierSet is not exposed through a compatible async method. Looking back at ReadXml, might seem like the answer to this problem. But a Task<Object> is not an interop-compatible type, which means I use ReadXmlAsync, which proxies the call through an IAsyncOperation:

public IAsyncOperation<Object> ReadXmlAsync(string filename, XmlType type)
{
    return (IAsyncOperation<Object>)AsyncInfo.Run((CancellationToken token) => ReadXml(filename, type));
}

AsyncInfo.Run starts a WinRT async operation and handles the returned result, regardless of the selected file path or type.

Level-based data is extracted in a similar manner to the tier data. The difference lies in the used internal models, as well as the node reading order:

Level ExtractLevelData(string levelString)
{
        XDocument document = XDocument.Parse(levelString);
    
        Level level = new Level();
        level.LevelMeta = new Meta();
     
        level.LevelMeta.Score = Convert.ToInt32(document.Root.Element("meta").Attribute("score").Value);
        level.LevelMeta.ButtonPrice = Convert.ToInt32(document.Root.Element("meta").Attribute("buttonPrice").Value)
        level.LevelMeta.LevelType = (LevelType)Convert.ToInt32(document.Root.Attribute("type").Value);
    
        int count = document.Root.Element("obstacles").Elements().Count();
        level.Obstacles = new Obstacle[count];
    
        count = 0;
        foreach (XElement element in document.Root.Element("obstacles").Elements())
        {
                Obstacle obstacle = new Obstacle();
                obstacle.HealthDamage = Convert.ToSingle(element.Attribute("healthDamage").Value);
                obstacle.InflictsDamage = Convert.ToBoolean(element.Attribute("inflictsDamage").Value);
                obstacle.Rotation = Convert.ToSingle(element.Attribute("rotation").Value);
                obstacle.Scale = Convert.ToSingle(element.Attribute("scale").Value);
                obstacle.X = Convert.ToSingle(element.Attribute("x").Value);
                obstacle.Y = Convert.ToSingle(element.Attribute("y").Value);
                obstacle.Type = (ObstacleType)Convert.ToInt32(element.Attribute("type").Value);
                level.Obstacles[count] = obstacle;
                count++;
        }
    
        count = document.Root.Element("monsters").Elements().Count();
        level.Monsters = new Monster[count];
    
        count = 0;
        foreach (XElement element in document.Root.Element("monsters").Elements())
        {
                Monster monster = new Monster();
                monster.CriticalDamage = Convert.ToSingle(element.Attribute("criticalDamage").Value);
                monster.Damage = Convert.ToSingle(element.Attribute("damage").Value);
                monster.DefaultAmmo = Convert.ToInt32(element.Attribute("defaultAmmo").Value);
                monster.MaxHealth = Convert.ToSingle(element.Attribute("maxHealth").Value);
                monster.X = Convert.ToSingle(element.Attribute("x").Value);
                monster.Y = Convert.ToSingle(element.Attribute("y").Value);
                monster.VelocityX = Convert.ToSingle(element.Attribute("velocityX").Value);
                monster.Lifetime = Convert.ToSingle(element.Attribute("lifetime").Value);
                monster.Type = (MonsterType)Convert.ToInt32(element.Attribute("type").Value);
                monster.Bonus = Convert.ToInt32(element.Attribute("bonus").Value);
                monster.Scale = Convert.ToSingle(element.Attribute("scale").Value);
        
                level.Monsters[count] = monster;
                count++;
        }
    
        count = document.Root.Element("buttons").Elements().Count();
        level.Buttons = new Button[count];
    
        count = 0;
        foreach (XElement element in document.Root.Element("buttons").Elements())
        {
                Button button = new Button();
        
                button.X = Convert.ToSingle(element.Attribute("x").Value);
                button.Y = Convert.ToSingle(element.Attribute("y").Value);
        
                level.Buttons[count] = button;
                count++;
        }
    
        count = document.Root.Element("powerups").Elements().Count();
        level.Powerups = new Powerup[count];
    
        count = 0;
        foreach (XElement element in document.Root.Element("powerups").Elements())
        {
                Powerup powerup = new Powerup();
        
                powerup.X = Convert.ToSingle(element.Attribute("x").Value);
                powerup.Y = Convert.ToSingle(element.Attribute("y").Value);
                powerup.Category = (PowerupCategory)Convert.ToInt32(element.Attribute("category").Value);
                powerup.Type = (PowerupType)Convert.ToInt32(element.Attribute("type").Value);
                powerup.Lifespan = Convert.ToSingle(element.Attribute("lifespan").Value);
                powerup.Effect = Convert.ToSingle(element.Attribute("effect").Value);
        
                level.Powerups[count] = powerup;
                count++;
        }
    
        Bear bear = new Bear();
        XElement bearElement = document.Root.Element("bear");
        bear.CriticalDamage = Convert.ToSingle(bearElement.Attribute("criticalDamage").Value);
        bear.Damage = Convert.ToSingle(bearElement.Attribute("damage").Value);
        bear.DefaultAmmo = Convert.ToInt32(bearElement.Attribute("defaultAmmo").Value);
        bear.MaxHealth = Convert.ToSingle(bearElement.Attribute("maxHealth").Value);
        bear.StartPosition = Convert.ToSingle(bearElement.Attribute("startPosition").Value);
        bear.Velocity = Convert.ToSingle(bearElement.Attribute("velocity").Value);
    
        level.GameBear = bear;
        
        return level;
}

As a result, the Level instance has an internal counterpart in the C++ project:

public sealed class Level
{
    public Bear GameBear { get; set; }
    public Meta LevelMeta { get; set; }
    public Obstacle[] Obstacles { get; set; }
    public Monster[] Monsters { get; set; }
    public Button[] Buttons { get; set; }
    public Powerup[] Powerups { get; set; }
}

From C# to C++ - Leveraging the WinRT Component

At this point, the C#-based WinRT component is complete and can be integrated into the C++ project. This can be done in two ways: either by adding a reference to the project itself or by adding a reference to the generated WinMD file. Both methods will ultimately produce the same output, but it’s easier to debug and modify coupled projects on the go, so I went with the first option.

To add a reference to an internal Windows Runtime Component project, right click on the C++ project in Solution Explorer and select Properties. You will see a dialog like this:

Select the Common Properties node in the tree on the left and open the Framework and References page:

In the sample screen capture above, the FallFury.XMLReader project is already added as a reference. For a new project, simply click on Add New Reference and add any compatible project or third-party extension. As soon as the reference is added, the publicly exposed methods can be accessed.

In DirectXPage.cpp I have a method called LoadLevelData that allows me to load the list of the registered levels from core.xml as well as build the visual tree for the menu items, whichallows players to select a level:

void DirectXPage::LoadLevelData()
{
    Coding4Fun::FallFury::XMLReader::Reader^ reader = ref new Coding4Fun::FallFury::XMLReader::Reader();
    Windows::Foundation::IAsyncOperation<Platform::Object^>^ result = reader->ReadXmlAsync("core.xml", Coding4Fun::FallFury::XMLReader::Models::XmlType::TIERS);
    result->Completed =
        ref new AsyncOperationCompletedHandler<Platform::Object^>(this, &DirectXPage::OnLevelLoadCompleted);
}

Following the normal asynchronous pattern, as well as the structure of the method exposed in the Reader class, I am calling ReadXmlAsync and getting the result in OnLevelLoadCompleted when the operation reaches its final stage. It is worth mentioning that the associated AsyncOperationCompletedHandler is invoked even when the reading fails; therefore, the invocation of that callback does not on its own mean that the necessary data is obtained:

Here is what happens when OnLevelLoadCompleted is called:

void DirectXPage::OnLevelLoadCompleted(IAsyncOperation<Platform::Object^> ^op, AsyncStatus s)
{
    if (s == AsyncStatus::Completed)
    {
        auto set = (Coding4Fun::FallFury::XMLReader::Models::TierSet^)op->GetResults();
        
        auto tiers = set->Tiers;
        
        int levelCounter = 0;
        
        for (auto tier = tiers->begin(); tier != tiers->end(); tier++)
        {
            StackPanel^ panel = ref new StackPanel();
            
            TextBlock^ levelTierTitle = ref new TextBlock();
            levelTierTitle->Text = (*tier)->Name;
            levelTierTitle->Style = (Windows::UI::Xaml::Style^)Application::Current->Resources->Lookup("LevelSelectTierItemText");
            levelTierTitle->RenderTransform = ref new TranslateTransform();
            panel->Children->Append(levelTierTitle);
            
            levelNames = (*tier)->LevelNames;
            auto levelFiles = (*tier)->LevelFiles;
            
            int max = levelNames->Length;
            
            for(int i = 0; i < max; i++)
            {
                MenuItem^ item = ref new MenuItem();
                item->Tag = levelCounter;
                item->Label = levelNames[i];
                item->HorizontalAlignment = Windows::UI::Xaml::HorizontalAlignment::Left;
                item->OnButtonSelected += ref new MenuItem::ButtonSelected(this, &DirectXPage::OnLevelButtonSelected);
                item->RenderTransform = ref new TranslateTransform();
                
                m_renderer->Levels.Insert(levelCounter,levelFiles[i]);
                
                panel->Children->Append(item);
                levelCounter++;
            }
            
            stkLevelContainer->Items->Append(panel);
        }
    }
}

Here, AsyncStatus can also be Cancelled or Error, so checking for Complete ensures that the expected result is processed further inside the context of the callback.

As the returned TierSet exposes the Tiers array, I am simply iterating through each of the existing items to create independent tier blocks, grouped in StackPanel elements, coupled with level-specific MenuItem instances that present the user with a choice of playing a given level. The level ID is carried in the Tag property and it will be used to identify the selected button when DirectXPage::OnLevelButtonSelected is triggered:

Reading Level-specific Data

Level data is read in the GamePlayScreen once the selected menu button passes the name and level identifiers. The LoadLevelXml method is called as the screen begins to load, preparing all assets for the start of the game session:

void GamePlayScreen::LoadLevelXML()
{
    Coding4Fun::FallFury::XMLReader::Reader^ reader = ref new Coding4Fun::FallFury::XMLReader::Reader();
    
    Platform::String^ LevelName = Manager->Levels.Lookup(StaticDataHelper::CurrentLevelID);
    
    Windows::Foundation::IAsyncOperation<Platform::Object^>^ result = 
            reader->ReadXmlAsync(LevelName, Coding4Fun::FallFury::XMLReader::Models::XmlType::LEVEL);
    
        result->Completed =
            ref new AsyncOperationCompletedHandler<Platform::Object^>(this, &GamePlayScreen::OnLevelLoadCompleted);
}

The selected ID passes from the menu screen to the game screen through CurrentLevelID, an intermediary value preserved in a StaticDataHelper class. The level file name is looked up based on the ID and then passed to ReadXmlAsync with the XmlType set to LEVEL. When the load completes, OnLevelLoadCompleted is invoked, and an additional helper class— LevelDataLoader—sets up the game components based on the received data:

void GamePlayScreen::OnLevelLoadCompleted(IAsyncOperation<Platform::Object^> ^op, AsyncStatus s)
{
        if (s == AsyncStatus::Completed)
        {
                InitializeSpriteBatch();    
        m_loader = ref new BasicLoader(Manager->m_d3dDevice.Get(), Manager->m_wicFactory.Get());
        CreateBear();
        
                LevelDataLoader^ loader = ref new LevelDataLoader((Coding4Fun::FallFury::XMLReader::Models::Level^)op->GetResults(), this);
        loader->SetupBear(GameBear);
        loader->SetupObstacles(m_obstacles);
        loader->SetupMonsters(m_monsters);
        loader->SetupButtons(m_buttons, m_buttonPrice);
        loader->SetupPowerups(m_powerups);
        m_currentLevelType = (LevelType) loader->CurrentLevel->LevelMeta->LevelType;
        
        StaticDataHelper::CurrentLevel = loader->CurrentLevel;
        StaticDataHelper::ButtonsTotal = loader->CurrentLevel->Buttons->Length;
        
        LoadTextures();
        
                CreateMonster();
                CreatePowerups();
        
        IsLevelLoaded = true;
        
        GameBear->TurnRight();
        m_particleSystem.CreatePreCachedParticleSets();
        LoadSounds();
        }
}

Each object is separated in its own method, such as SetupBear or SetupObstacles. SetupBear, for example, transforms the exposed managed Bear model to a native C++ Characters::Bear one:

void LevelDataLoader::SetupBear(Bear ^gameBear)
{
        gameBear->Position = float2(GetXPosition(CurrentLevel->GameBear->StartPosition), 0);    
    gameBear->MaxHealth = CurrentLevel->GameBear->MaxHealth;
    gameBear->CurrentHealth = CurrentLevel->GameBear->MaxHealth;
    gameBear->CurrentDamage = CurrentLevel->GameBear->Damage;
    gameBear->Velocity.y = CurrentLevel->GameBear->Velocity;
    gameBear->MaxCriticalDamage = CurrentLevel->GameBear->CriticalDamage;
    gameBear->Rotation = 0.0f;
}

Conclusion

Mixing C# and C++ components is not a complicated process. Nonetheless, it comes with specific restrictions and considerations, such as the format of the publicly exposed asynchronous calls. The above C#-based level loading engine highlights the fact that WinRT interoperability allows you to leverage the languages you know best in order to efficiently accomplish project tasks.

One of the goals set when developing FallFury was making the game extensible in regards to playable levels. Furthermore, I thought that it would make sense from the development and testing perspective to have levels as a completely separate entity that can be modified as necessary. For example, when a new power-up was introduced, I wanted to add an extra line in a level file and test it out. This was ultimately achieved by creating an XML-based level engine and in this article I will describe the level structure and design process.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-5-Creating-Levels.  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

The First Steps

When I started working on the level engine concept, I began designing the potential XML file structure for the level and ended up with the following requirements:

• Level Type Identifier – As different levels have different backgrounds and sound themes, there should be a way to mark a level type. There are currently four level types: dream, nightmare, space, and magic bean.
• The Starting Character Descriptor – When the game starts, the teddy bear has some initial, basic properties, such as maximum health level, horizontal position, and velocity.
• A Collection of Obstacles – For each level, obstacles are positioned differently, and it’s important to specify that. For some obstacles it might be desirable to disable the damage infliction component, while for others it might be good to maximize the damage caused by colliding with them. Also, there are multiple textures associated with different obstacle types, so I wanted to specify the obstacles to render regardless of the selected level type.
• A Collection of Monsters – Obstacles are not the only component that can damage the bear during gameplay. There are also monsters that can pop up and shoot at the main character. Similar to the bear, monsters represent a living entity and have some specific properties, such as the initial health, damage, starting position, velocity, and type.
• Buttons – These are the bonus point boosters in FallFury. The player collects as many of those as possible, and each of them should be individually positioned to form either a trail or a shape.
• Power-Ups – With the basic set of abilities, the bear is able to get some bonuses such as a cape that will speed-up his descent or a bubble that will protect him from incoming shells.

The first build of the level engine integrated into FallFuryused percentage-based relative values to position elements on the screen. Although this seemed like a good idea at the time, it became problematic because

• It required the level to be a fixed size, which restricted element addition and level extension.
• It caused problems with obstacles that needed to be scaled and therefore had a non-standard size.
• Small modifications were harder to make because minimal adjustments would throw off the relative position.

So, I switched to a pixel-based conditioning in which each position is relative to zero. With this in place, levels can be infinitely long (within the context of the machine’s rendering and memory capabilities)and extra elements can be more seamlessly added.

Additionally, levels need to be packaged together in individual sets, normally grouped by themes, without restriction. This is achieved with the help of an extra XML file,called core.xml, which keeps track of level tiers, and acts as a container that allows the developer to name and easily enable or disable specific levels .

The structure for the core.xml file looks like this:

<tiers>
  <tier name="GO, GO, TEDDY">
    <level name="mind travels" file="GoGoTeddy\mind.xml"></level>
    <level name="falling in" file="Nightmare\full_pilot.xml"></level>
    <level name="frontlines" file="Nightmare\the_beginning.xml"></level>
    <level name="the chase" file="Nightmare\chasing_monsters.xml"></level>
  </tier>
  <tier name="SECRET GARDEN">
    <level name="bean stalking" file="Garden\bean_stalking.xml"/>
    <level name="thorn apart" file="Garden\thorn_apart.xml"/>
  </tier>
  <!--<tier name="Obstacle ***TEST***">
    <level name="Nightmare 0" file="test\Obstacle\nightmare\0.xml" />
    <level name="Nightmare 1" file="test\Obstacle\nightmare\1.xml" />
    <level name="Bean 0" file="test\Obstacle\bean\0.xml" />
    <level name="Bean 1" file="test\Obstacle\bean\1.xml" />
    <level name="Dream 0" file="test\Obstacle\dream\0.xml" />
    <level name="Dream 1" file="test\Obstacle\dream\1.xml" />
  </tier>-->
  <!--<tier name="Death ***TEST***">
    <level name="Monster 0" file="test\death\0.xml" />
  </tier>-->
  <!--<tier name="Monster ***TEST***">
    <level name="0" file="test\Monsters\0.xml" />
    <level name="1" file="test\Monsters\1.xml" />
    <level name="2" file="test\Monsters\2.xml" />
    <level name="3" file="test\Monsters\3.xml" />
    <level name="4" file="test\Monsters\4.xml" />
    <level name="5" file="test\Monsters\5.xml" />
    <level name="6" file="test\Monsters\6.xml" />
    <level name="7" file="test\Monsters\7.xml" />
    <level name="8" file="test\Monsters\8.xml" />
    <level name="9" file="test\Monsters\9.xml" />
    <level name="10" file="test\Monsters\10.xml" />
  </tier>-->
  <!--<tier name="MEDALS *****TEST******">
    <level name="gold" file="test\Medals\gold.xml"></level>
    <level name="silver" file="test\Medals\silver.xml"></level>
    <level name="bronze" file="test\Medals\bronze.xml"></level>
  </tier>
  <tier name="Buttons ***TEST***">
    <level name="1" file="test\Buttons\single.xml" />
    <level name="Lots" file="test\Buttons\multiple.xml" />
  </tier>
  <tier name="Obstacles ***TEST***">
    <level name="Cape" file="test\PowerUps\0.xml" />
  </tier>-->
</tiers>

Tiers that are commented out are ignored and the included levels aren’t on the game list. Also, the paths indicated for each file attribute—for each individual tier—are relative to the game folder itself. There is no limit on the number of subfolders that can be included in the path. The above structure will render this level set:

The Level XML

Let’s now take a look at the layout of the level descriptor XML file:

<?xml version="1.0" encoding="utf-8" ?>
<level type="0">
  <meta score="0" buttonPrice="10"></meta>
  <bear maxHealth="100" startPosition="300" velocity="8.0" damage="11" criticalDamage="20" defaultAmmo="100" />
  <obstacles>
    <obstacle type="1" x="119" y="2300" inflictsDamage="true" healthDamage="5" rotation="3.14" scale="1" />
    <obstacle type="3" x="534.5" y="3000" inflictsDamage="true" healthDamage="5" rotation="0" scale="1" />
    <obstacle type="3" x="534.5" y="3300" inflictsDamage="true" healthDamage="5" rotation="0" scale="1" />
    <obstacle type="1" x="119" y="4200" inflictsDamage="true" healthDamage="5" rotation="3.14" scale="1" />
    <obstacle type="2" x="546" y="5000" inflictsDamage="true" healthDamage="5" rotation="0" scale="1" />
    <obstacle type="1" x="119" y="5800" inflictsDamage="true" healthDamage="5" rotation="3.14" scale="1" />
    <obstacle type="2" x="546" y="6600" inflictsDamage="true" healthDamage="5" rotation="0" scale="1" />
  </obstacles>
  <monsters>
    <monster lifetime="3000" scale=".2" velocityX="2" velocityY="2" type="0" x="460" y="19900" maxHealth="80" bonus="100" lives="0" damage="10" criticalDamage="8" defaultAmmo="50" />
    <monster lifetime="3000" scale=".2" velocityX="2" velocityY="2" type="1" x="460" y="25000" maxHealth="80" bonus="100" lives="0" damage="10" criticalDamage="8" defaultAmmo="50" />
    <monster lifetime="3000" scale=".2" velocityX="2" velocityY="2" type="2" x="460" y="34500" maxHealth="80" bonus="100" lives="0" damage="10" criticalDamage="8" defaultAmmo="50" />
    <monster lifetime="6000" scale=".4" velocityX="2" velocityY="2" type="3" x="460" y="41400" maxHealth="180" bonus="100" lives="0" damage="17" criticalDamage="8" defaultAmmo="50" />
  </monsters>
  <buttons>
    <button x="300" y="800" />
    <button x="360" y="800" />
    <button x="300" y="860" />
    <button x="360" y="860" />
    <button x="300" y="920" />
    <button x="360" y="920" />
    <button x="300" y="980" />
    <button x="360" y="980" />
  </buttons>
  <powerups>
    <powerup category="1" type="4" x="140" y="9200" effect="3" lifespan="4"></powerup>
    <powerup category="1" type="3" x="480" y="19800" effect="10" lifespan="6"></powerup>
    <powerup category="1" type="0" x="480" y="27500" effect="10" lifespan="6"></powerup>
    <powerup category="1" type="1" x="100" y="34000" effect="10" lifespan="6"></powerup>
    <powerup category="1" type="0" x="100" y="41200" effect="10" lifespan="6"></powerup>
  </powerups>
</level>

The opening level tag carries a type attribute. This is level theme flag. It can be set to one of the three four values:

• 0 – The Nightmare Theme
• 1 – The Magic Bean Theme
• 2 – The Dream Theme
• 3 – The Space Theme

You can see the design differences in the images below:

Remember, that obstacles and the level theme itself do not influence much other than the background and soundboard.

Once the type is specified, the meta tag brings up the score and buttonPrice attributes. If you for some reason want to create a level including an initial score, you can specify it here. And because buttons are fixed bonus assets that are all created equal, each of them carries a given bonus point weight. The score based on the collected buttons is calculated at the end of the game and relies on the value specified in the meta tag.

Obstacles

Next comes the obstacle collection, which is represented by the obstacles tag. This tag is required even if there are no obstacles on a given level. Simply use <obstacles /> as necessary. Each child node represents an instance of an obstacle that can be choosen from the following enum:

enum class ObstacleType
{
    OT_CLOUD = 0,
    OT_SPIKE_NIGHTMARE_LARGE = 1,
    OT_SPIKE_NIGHTMARE_MEDIUM = 2,
    OT_SPIKE_NIGHTMARE_SMALL = 3,
    OT_BEAN_A = 4,
    OT_BEAN_B = 5,
    OT_BEAN_C = 6,
    OT_BEAN_D = 7,
    OT_BEAN_E = 8,
    OT_SPACE_ROCKET = 9,
    OT_SPACE_COMET_A = 10,
    OT_SPACE_COMET_B = 11,
    OT_SPACE_SATELLITE = 12,
    OT_SPACE_UFO = 13,
    OT_SPACE_BALL = 14
};

Here is the complete table showing the appearance of each of them:

No matter how the obstacles are positioned, they will either be located in the visible area or displaced outside the viewport and not displayed. The ultimate position is taken from the obstacle size and is relative to the center of the texture. For example, if an obstacle texture is 400- pixels wide, the X-relative position should be set to 200. If the position differs from the starting one, however, the obstacle texture is cut to include the area that fits in the 768 pixel wide playable zone visible. There are no restrictions regarding the Y position.

To help in level creation, some obstacles have pre-defined left and right margins. For example:

• OT_BEAN_A: 269.5 (Left), 498.5 (right, with 3.14 rotation)
• OT_BEAN_B: 128.5 (left), 638.5 (right, with 3.14 rotation)
• OT_BEAN_C: 172 (left), 596 (right, with 3.14 rotation)
• OT_BEAN_D: 188.5 (left), 579.5 (right, with 3.14 rotation)
• OT_BEAN_E: 206.5 (left), 561.5 (right, with 3.14 rotation)

The inflictsDamage attribute determines whether the obstacle harms the main character. If it is set to false, the character will still make the sound of colliding with it but will not lose any health points. The primary use for this attribute is level testing.If it is set to true, the character will loose the amount of health points indicated by the healthDamage attribute.

The rotation and scale attributes can be used to flip and resize the texture as needed. Rotation is measured in radians, and the scale is a normalized value in which 1.0 represents 100% of the scale.

Monsters

As with obstacles, the monsters node should never be omitted from the file and should at least contain a placeholder: <monsters />. Unlike obstacles, however, monsters are dynamic and do not have fixed positions. Moreover, monsters have limited active time during gameplay. The first attribute,lifetime, determines the length of the fall during which the monster will be visible in the viewport. With the y attribute as the Y-based position at which the monster appears, at the y+lifetime position the monster simply flies away if not killed.

The scale attribute carries the same purpose as the one for the obstacle—normalized texture size relative to the size of the original image file. As such, the level designer does not have to worry about linking the width and height of the monster when resizing and can instead use a percentage-like value to scale the monster up or down, simultaneously modifying both the width and the height with zero stretching.

Nextup are velocityX and velocityY. These two attributes are used to set the motion velocity when the monster is already visible. Instead of being a static shooting entity, the enemy moves on a randomized zig-zag path at the bottom of the screen. The horizontal and vertical displacement—in pixels, per update cycle—is individually set through the values carried by the above-mentioned attributes. If necessary, this functionality can be disabled in the code-behind by assigning a fixed value for the vertical and horizontal movement for all monsters that are being loaded on a given level.

The monster type is an integer value that is translated in a value from the following enum (located in MonsterType.h):

enum class MonsterType
{
    MT_NIGHTMARE_A = 0,
    MT_NIGHTMARE_B = 1,
    MT_NIGHTMARE_C = 2,
    MT_MAGICBEAN_A = 3,
    MT_MAGICBEAN_B = 4,
    MT_MAGICBEAN_C = 5,
    MT_CANDYLAND_A = 6,
    MT_CANDYLAND_B = 7,
    MT_CANDYLAND_C = 8,
    MT_CANDYLAND_D = 9,
    MT_CANDYLAND_E = 10
};

Here is a table that shows the texture associated with each identifier:

Each monster has three separate textures associated with it. The three textures are cycled inside the update loop for each monster entity when the monster becomes visible, creating the movement effect:

Each monster currently shoots only one type of ammo: a red plasma ball. Be aware, however, that there is a preprogrammed condition in which the last monster in the XML file collection is automatically considered the final boss. This means the scale, maxHealth and lifetime properties must be manually adjusted to reflect the effect. Without doing so, the last monster will, regardless of the XML setting, switch in-game to a triple fireball shot that inflicts three times the damage indicated by the damage attribute:

Each monster can have limited ammo as set by the defaultAmmo attribute. In the case that the ammo is exhausted before the monster expires, the monster will continue its motion at the bottom of the screen without inflicting direct damage to the main character.

Buttons

These are the least complex entities and only carry an X and a Y position. Given those coordinates, relative to the left margin of the visible area, a button texture is rendered:

Once picked-up, the button counter is increased by one and the meta-score incremented by the value set in the meta tag at the beginning of the level XML as long as the feature is activated in the code-behind.

Power-ups

To make the game more fun, there are bonus elements that can be picked up by the bear in order to enhance its performance or protection. These elements are declared in the <powerups/> collection. First and foremost, it is important to declare whether the power-up is positive or negative. In the current version of FallFury, only positive power-ups are included. Nonetheless, the harness for negative ones is already integrated in the parser. Therefore, the category attribute should be set to 1 if the power-up has a positive effect and 0 for a negative effect. This value will only have an effect over the sound played when the bonus is collected.

The power-up type can be one of the following (enum located in PoweupType.h):

enum class PowerupType
{
    HEALTH = 0,
    HELMET = 1,
    PARACHUTE = 2,
    BUBBLE = 3,
    CAPE = 4,
    AXE = 5,
    BOOMERANG = 6,
    HAMMER = 7,
    KNIFE = 8,
    PLASMA_BALL = 9,
    CIRCLE = 10
};

The table below shows the power-up texture appearance. Behaviors are already defined in the game and influenced by only the effect and lifespan (seconds) attributes:

CIRCLE is a helper power-up that has no effect on the bear and is instead used as an additional texture overlay along with any other power-up in order to create a pulsating circle effect.

Conclusion

FallFury ships with a dozen of sample levels that showcase all of the elements described in the article. At the moment, a level editor is in the works, but it isn’t too complicated to build XML files manually. To do so, you need to consider the pixel-based locations and ensure that they’re all in the visible area—the game engine will automatically handle all other displacements and adjustments.

The Concept of a Swap Chain

Before I go into detail about the DirectX and XAML interop in FallFury, I want to cover one important aspect of DirectX development that you need to familiarize yourself with: the swap chain.

When your graphics adapter draws on the visual surface, you, as the user, see only minor potential redraws. Internally, however, the device switches buffers that reflect the displayed content, with each buffer representing a frame that has to be drawn. You can deduce from this that any swap chain has at least two buffers that it can switch between.

For example, if I want to display my character as being displaced by a specific amount of pixels, the buffer will at the outset present to me the character in its initial position, while the second buffer will be constructed in the background with the proper position adjustments. The first frame, made from the content from the first buffer, will be discarded, and then the second frame will be displayed, and so on. This process occurs at a very high speed that depends on the processing capabilities of the graphics adapter, so the user does not notice the swapping itself.

The most common swap chain is composed of two buffers—the screenbuffer and the secondary framebuffer.

SwapChainBackgroundPanel

DirectX interoperability with XAML simplifies a lot of routine tasks that would otherwise be handled with manual rendering procedures, such as a menu system or a simple game HUD. That being said, the way the XAML workflow is organized in a Direct2D project is quite different compared to a standard XAML Windows Store or Windows Phone application.

The core difference is that there is no navigational system per-se and the fundamental entity in a Direct2D (XAML) project that manages the XAML content is a SwapChainBackgroundPanel control. This control allows the developer to overlay XAML elements on top of the DirectX renders. It replaces the normal page-based layout with one in which it is sole container for every XAML control that has to be used in the application. This necessitates that you will have to organize the secondary elements in such a way that the correct set is displayed for the current application state.

For example, if the user is in the main menu, menu options as well as the game logo should be shown. When the user switches to the game mode, the HUD should appear and the menu should become hidden. Although both the menu and the HUD are a part of the same SwapChainBackgroundPanel, I will have to manually manage state and visibility changes.

Using the SwapChainBackgroundPanel also means that you will have to enforce specific graphic configuration rules in your application. One of them applies to setting up the swap chain. When you set up the scaling, it must be set to DXGI_SCALING_STRETCH:

DXGI_SWAP_CHAIN_DESC1 swapChainDesc = {0};
swapChainDesc.Width = static_cast<UINT>(m_renderTargetSize.Width); 
swapChainDesc.Height = static_cast<UINT>(m_renderTargetSize.Height);
swapChainDesc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
swapChainDesc.Stereo = false; 
swapChainDesc.SampleDesc.Count = 1;
swapChainDesc.SampleDesc.Quality = 0;
swapChainDesc.BufferUsage = DXGI_USAGE_RENDER_TARGET_OUTPUT;
swapChainDesc.BufferCount = 2;
swapChainDesc.Scaling = DXGI_SCALING_STRETCH;
swapChainDesc.SwapEffect = DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL;
swapChainDesc.Flags = 0;

The swap chain itself should be configured for composition, mixing the native DirectX buffer with the overlaid XAML. This is done by calling CreateSwapChainForComposition:

ThrowIfFailed(
    dxgiFactory->CreateSwapChainForComposition(
        m_d3dDevice.Get(),
        &swapChainDesc,
        nullptr,
        &m_swapChain
        )
    );

ComPtr<ISwapChainBackgroundPanelNative> panelNative;
ThrowIfFailed(
    reinterpret_cast<IUnknown*>(m_panel)->QueryInterface(IID_PPV_ARGS(&panelNative))
    );

ThrowIfFailed(
    panelNative->SetSwapChain(m_swapChain.Get())
    );

There really isn’t much additional configuration work beyond this point. Remember, that the XAML content will always be overlaid on top of the DirectX content; therefore, plan the game components accordingly.

The XAML Menu System

The menu is at the core of the FallFury experience. When designing it, I was inspired by how Dance Central built the user interaction mechanism, and I tried to implement a similar approach in which the user would have to slide the button to the right instead of simply tapping on it:

Each menu item is built around a custom MenuItem control (MenuItem.xaml):

<UserControl
    x:Class="Coding4Fun.FallFury.MenuItem"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:Coding4Fun.FallFury"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    x:Name="menuItem"
    Margin="10, 0, 0, 10">

    <Grid 
        Height="65" 
        ManipulationMode="TranslateX"
        ManipulationCompleted="Grid_ManipulationCompleted"
        ManipulationDelta="Grid_ManipulationDelta" 
        x:Name="ControlContainer"
        PointerPressed="Grid_PointerPressed" 
        PointerReleased="Grid_PointerReleased">
        
        <Grid.Resources>
            <Storyboard x:Name="ArrowAnimator">
                <DoubleAnimation Storyboard.TargetName="ImageTranslateTransform"
                                 Storyboard.TargetProperty="X"
                                 From="0"
                                 To="20"
                                 Duration="0:0:0.4"
                                 RepeatBehavior="Forever"
                                 AutoReverse="True">
                </DoubleAnimation>
            </Storyboard>

        </Grid.Resources>
        
        <Grid.RowDefinitions>
            <RowDefinition Height="10" />
            <RowDefinition />
            <RowDefinition />
            <RowDefinition Height="10" />
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="10" />
            <ColumnDefinition />
        </Grid.ColumnDefinitions>
        <StackPanel Orientation="Horizontal" Grid.RowSpan="4" Grid.ColumnSpan="4">
            <!-- width is sent in code behind, have to get this dynamic ...  -->
            <Grid Width="350" x:Name="coverRectangle">
                <Rectangle Fill="#303030" />
                <Rectangle 
                    Fill="Red" 
                    x:Name="coverActiveRectangle" />
            </Grid>
            <Image x:Name="MenuImage" Source="ms-appx:///MenuItems/single_arrow.png" Margin="10,0,0,0" Stretch="Uniform">
                <Image.RenderTransform>
                    <TranslateTransform x:Name="ImageTranslateTransform"></TranslateTransform>
                </Image.RenderTransform>
            </Image>
        </StackPanel>
        <!---->

        <TextBlock 
            Text="{Binding ElementName=menuItem, RelativeSource={RelativeSource Self}, Path=Label}"
            Grid.RowSpan="4"
            Grid.ColumnSpan="4"
            Style="{StaticResource MenuItemText}">

        </TextBlock>
        
        <MediaElement x:Name="coreMenuMedia" Source="ms-appx:///Assets/Sounds/MenuTap.wav" AutoPlay="False"></MediaElement>
        <MediaElement x:Name="slideMenuMedia" Source="ms-appx:///Assets/Sounds/MenuSlide.wav" AutoPlay="False"></MediaElement>
    </Grid>
</UserControl>

There is a core storyboard that is used to perform an image bounce. Initial tests showed that that most users tend to follow the standard “click-and-go” pattern and even though the implemented button was a slider, they tried to click it at least once, expecting the game to take them to the next screen. To avoid this, I introduced a visual arrow indicator that bounces left and right to indicate the direction of the necessary slide.

When the sliding occurs, the overlay grid width is being adjusted relative to the manipulation. At the same time, the button changes from passive state (dark background):

to active state (red background):

Internally, the double-arrow image replaces the single-arrow one and is translated across the X-axis to create a bouncing effect:

void MenuItem::Grid_PointerPressed(Platform::Object^ sender, Windows::UI::Xaml::Input::PointerRoutedEventArgs^ e)
{
    BitmapImage^ image = ref new BitmapImage(ref new Uri("ms-appx:///MenuItems/double_arrow.png"));
    MenuImage->Source = image;
    
    coverActiveRectangle->Visibility = Windows::UI::Xaml::Visibility::Visible;
    ((Storyboard^)ControlContainer->Resources->Lookup("ArrowAnimator"))->Begin();
    
    coreMenuMedia->Play();
}

As the user drags the finger on the button, the red overlay size should be adjusted accordingly. The size adjustment can be easily tracked in the ManipulationDelta event handler for the focused grid:

void MenuItem::Grid_ManipulationDelta(Platform::Object^ sender, Windows::UI::Xaml::Input::ManipulationDeltaRoutedEventArgs^ e)
{
    double diff = e->Cumulative.Translation.X;
    
    if (diff > maxDeltaSize)
    {
        diff = maxDeltaSize;
    }
    else if (diff < 0)
    {
        diff = 0;
    }
    
    coverRectangle->Width = initialBarWidth + diff;
}

When the user action on the button is completed, the ManipulationCompleted event handler is triggered on the same overlay grid. If the relative drag hits the critical threshold, the action linked to the button should be invoked:

void MenuItem::Grid_ManipulationCompleted(Platform::Object^ sender, Windows::UI::Xaml::Input::ManipulationCompletedRoutedEventArgs^ e)
{
    float diff = e->Cumulative.Translation.X;
    
    if (diff > maxDeltaSize - 50) // slight buffer
    {
        slideMenuMedia->Play();
        OnButtonSelected(this, Label);
    }
    
    ResetElements();
}

There are also local sound effects that are played when the slider-button is tapped and moved to the end. Both are handled by separate MediaElement controls that avoid an internal sound file switch, calling instead the Play method as necessary. The OnButtonSelected event handler can be dynamically hooked in the application backend.

Each button also has a visible content area that can display a text label. It can be set through a DependencyProperty:

DependencyProperty^ MenuItem::_LabelProperty = 
    DependencyProperty::Register("Label", 
    Platform::String::typeid,
    MenuItem::typeid, 
    nullptr);

In its current configuration, the menu label can be also set in XAML:

<local:MenuItem x:Name="btnNewGame" Label="new game">
    <local:MenuItem.RenderTransform>
        <TranslateTransform></TranslateTransform>
    </local:MenuItem.RenderTransform>
</local:MenuItem>

When the button loses the focus, the state resets to the passive one, stopping the animation and resetting the arrow image to the single one:

void MenuItem::ResetElements()
{
    BitmapImage^ image = ref new BitmapImage(ref new Uri("ms-appx:///MenuItems/single_arrow.png"));
    MenuImage->Source = image;
    
    ((Storyboard^)ControlContainer->Resources->Lookup("ArrowAnimator"))->Stop();
    
    coverRectangle->Width = initialBarWidth;
    coverActiveRectangle->Visibility = Windows::UI::Xaml::Visibility::Collapsed;
}

That’s about as complex as the menu item control will get. The menu container itself can be any Grid or StackPanel control. The way the menu items are used across the game states, there is no need to have a separate unified container.

The Main XAML Container & State Changes

Going back to DirectXPage.xaml, there are several parts of the XAML layout that should be highlighted. First and foremost, the game curtains—the static parts of the screen that are being displayed instead of blacking out parts of the viewport that are not being used when the game runs in landscape mode. Because the game includes a rectangular frame instead of stretching the entire playable area to the size of the screen, there is an unknown amount of unallocated visual space on both the right and left sides of the frame itself:

<Grid HorizontalAlignment="Left" x:Name="containerA">
    <Rectangle Fill="#09bbe3" />

    <Rectangle Width="10" HorizontalAlignment="Left">
        <Rectangle.Fill>
            <LinearGradientBrush StartPoint="0,0" EndPoint="1,0">
                <GradientStop Color="#a000" Offset="0.0"></GradientStop>
                <GradientStop Color="#0000" Offset="1.0"></GradientStop>
            </LinearGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</Grid>

<Grid HorizontalAlignment="Right" x:Name="containerB">
    <Rectangle Fill="#09bbe3" />

    <Rectangle Width="10" HorizontalAlignment="Right">
        <Rectangle.Fill>
            <LinearGradientBrush StartPoint="1,0" EndPoint="0,0">
                <GradientStop Color="#a000" Offset="0.0"></GradientStop>
                <GradientStop Color="#0000" Offset="1.0"></GradientStop>
            </LinearGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</Grid>

Although these two grids have set alignments, the actual location on the screen will be set in code-behind because the size will also be re-calculated. Also, I need to make sure that the application is in the full display mode—if it is snapped, there is no need to display the curtains because the visible area will be reduced to an overlay grid.

The curtain resize and visibility are determined in the UpdateWindowSize method:

void DirectXPage::UpdateWindowSize()
{
    bool visibility = true;
    if (ApplicationView::Value == ApplicationViewState::Snapped)
            visibility = false;
    
    float margin = (m_renderer->m_renderTargetSize.Width - 768.0f) / 2.0f;
    if (margin < 2.0)
            visibility = false;
    
    if (visibility)
    {
        containerA->Width =  margin;
        containerA->HorizontalAlignment = Windows::UI::Xaml::HorizontalAlignment::Right;
        containerB->Width =  margin;
        containerB->HorizontalAlignment = Windows::UI::Xaml::HorizontalAlignment::Left;
        containerA->Visibility = Windows::UI::Xaml::Visibility::Visible;
        containerB->Visibility = Windows::UI::Xaml::Visibility::Visible;
    }
    else
    {
        containerA->Visibility = Windows::UI::Xaml::Visibility::Collapsed;
        containerB->Visibility = Windows::UI::Xaml::Visibility::Collapsed;
    }
}

The snippet above ensures that the curtains will only be displayed when there is extra, unused space in addition to the 768 pixels taken by the playable area.

Let’s take a look at state-specific content that is being displayed whenever the game switches states. Because of the nature of DirectX interaction, there is no way for me to hook to specific event handlers from the native loop. Therefore, I need to constantly check that the content displayed is associated with the current state.

This can be done with the help of the SwitchGameState method:

void DirectXPage::SwitchGameState()
{
    switch (m_renderer->CurrentGameState)
            {
            case GameState::GS_FULL_WIN:
                    {
                            grdCompleteWin->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_PLAYING:
                    {
                            Hud->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_MAIN_MENU:
                    {
                            stkMainMenu->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_GAME_OVER:
                    {
                            UpdateResults();
                            ResultPanel->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            grdGameOver->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_SUBMIT_SCORE:
                    {
                            grdSubmitScore->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            txtSubmitScoreView->Text = StaticDataHelper::Score.ToString();
                            break;
                    }
            case GameState::GS_TOP_SCORES:
                    {
                            grdTopScores->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_WIN:
                    {
                            UpdateResults();
                            grdWinner->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            ResultPanel->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_ABOUT_SCREEN:
                    {
                            grdAbout->Visibility =  Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_LEVEL_SELECT_SINGLE:
                    {
                            animationBeginTime = 0;
            
                            stkLevelSelector->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            break;
                    }
            case GameState::GS_HOW_TO:
                    {
                            grdHowTo->Visibility = Windows::UI::Xaml::Visibility::Visible;
                            Storyboard^ howToInitialBoard = (Storyboard^)grdMain->Resources->Lookup("StoryboardChainA");
                            howToInitialBoard->Begin();
                            break;
                    }
        default:
                    break;
            }
    
            Storyboard^ loc = (Storyboard^)grdMain->Resources->Lookup("FadingOut");
            loc->Begin();
}

One thing you’ve probably noticed about the snippet above is the fact that there is no indicator showing that controls are being hidden when the state changes. Just calling SwitchGameState in the Update loop would cause multiple controls to be displayed at once. However, there is also the HideEverything method that goes through the visual tree and sets the Visibility to Collapsed for everything:

void DirectXPage::HideEverything()
{
    for (uint i = 0; i < grdMain->Children->Size; i++)
    {
        grdMain->Children->GetAt(i)->Visibility = Windows::UI::Xaml::Visibility::Collapsed;
    }
}

HUD Interaction

The Heads-Up Display (HUD) is used to alert the player about the current state of the game and the game character. In FallFury, it is used to display three indicators: how many buttons the character collected, how much time it took the character to get to the current level part, and current character health. It is also the container for the Pause button.

Here is the visual representation:

Here is the underlying XAML:

<Grid x:Name="Hud" VerticalAlignment="Top" Visibility="Collapsed">
    <Grid.RowDefinitions>
        <RowDefinition Height="80" />
        <RowDefinition Height="Auto" />
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition />
        <ColumnDefinition />
        <ColumnDefinition />
        <ColumnDefinition Width="80" />
    </Grid.ColumnDefinitions>

    <Rectangle Fill="Black" Grid.ColumnSpan="4" />

    <Button
        Grid.Column="0"
        x:Name="btnPause"
        Click="btnPause_Click"
        Style="{StaticResource PauseButton}">
        <Image Source="ms-appx:///Assets/HUD/pauseButton.png" Stretch="None" /
    </Button>

    <StackPanel Grid.Column="1" Orientation="Horizontal">
        <Image Source="ms-appx:///Assets/HUD/buttonHud.png" Stretch="None" />

        <TextBlock
            x:Name="txtButtons"
            Text="0"
            Style="{StaticResource hudResult}"/>
    </StackPanel>

    <StackPanel Grid.Column="2" Orientation="Horizontal">
        <Image Source="ms-appx:///Assets/HUD/clockHud.png" Stretch="None" />

        <TextBlock
            x:Name="txtTimer"
            Text="00:00"
            Style="{StaticResource hudResult}"/>
    </StackPanel>

    <Image
        Grid.Column="3"
        Source="ms-appx:///Assets/HUD/heartHud.png"
        Stretch="None" />

    <Grid
        Grid.Column="3"
        Grid.Row="1">
        <Rectangle Fill="Black" Opacity=".8"/>
        <controls:HealthBar x:Name="healthBar"></controls:HealthBar>
    </Grid>
</Grid>

As I mentioned before, the DirectX layer cannot directly interact with the XAML layer. Therefore, there needs to be an intermediary binding class. As the game progress changes, the UpdateHUD method is called, taking a reference to the current DirectX screen and reading the game data from the character and the StaticDataHelper class, which is the container for the time elapsed:

void DirectXPage::UpdateHud(GamePlayScreen^ playScreen)
{
    healthBar->Update(playScreen->GameBear->CurrentHealth, playScreen->GameBear->MaxHealth);
    
    txtButtons->Text = StaticDataHelper::ButtonsCollected.ToString();
    
    // Find a better built-in string formatting code
    if (m_renderer->CurrentGameState == GameState::GS_PLAYING && !(StaticDataHelper::IsPaused) && playScreen->IsLevelLoaded)
    {
        StaticDataHelper::SecondsTotal += m_timer->Delta;
        
        txtTimer->Text = StaticDataHelper::GetTimeString((int)StaticDataHelper::SecondsTotal);
    }
}

As seen above, part of the HUD is taken by a health indicator control—HealthBar. It is a simple composite element made out of two overlaying rectangles, one of which is resized as the bear health changes:

<UserControl
    x:Class="Coding4Fun.FallFury.Controls.HealthBar"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:FallFury"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="410"
    d:DesignWidth="20" Height="410" Width="20">
    
    <Grid>
        <StackPanel VerticalAlignment="Top" Margin="0, 5, 0,20">
            <Rectangle Height="400" Style="{StaticResource HealthRectangle}" />
        </StackPanel>

        <StackPanel VerticalAlignment="Top" Margin="0, 5, 0, 10">
            <Rectangle x:Name="OverlayStacker" Height="0" Style="{StaticResource HealthOverlayRectangle}" />
        </StackPanel>
    </Grid>
</UserControl>

Being of a fixed size, it is fairly easy to calculate the health-to-damage ratio and display that as the size of the overlaid rectangle:

DependencyProperty^ HealthBar::_MaxHealthProperty = 
    DependencyProperty::Register("MaxHealth", 
    double::typeid,
    HealthBar::typeid, 
    nullptr);

DependencyProperty^ HealthBar::_CurrentHealthProperty = 
    DependencyProperty::Register("CurrentHealth", 
    double::typeid,
    HealthBar::typeid, 
    nullptr);

void HealthBar::Update(double currentHealth, double maxHealth)
{
    CurrentHealth = currentHealth;
    MaxHealth = maxHealth;
    
    if (CurrentHealth >= 0)
    {
        OverlayStacker->Height = 400.0 - ((400.0 * CurrentHealth) / MaxHealth);
    }
}

Conclusion

Using XAML as a part of a DirectX application does not require the developer to do a massive overhaul of the infrastructure. That said, be mindful when deciding whether to use a hybrid XAML application, as it is much easier to integrate a SwapChainBackgroundPanel with the underlying DirectX configuration from the ground up instead of trying to do so when the DirectX component is completed.

The Background

Each game screen in FallFury has a moving background that creates the illusion of a fall. The way the screen is designed, it simulates vertical parallax scrolling, as the background moves faster than the overlaid objects. There is a simple way to make background movement possible without actually having to replicate parts of the texture and render them all over again. Take a look at this image, showcasing the process:

First of all, two textures are loaded that, connected at the bottom, create the illusion of a single texture. In the beginning, texture A takes the entire screen and texture B is positioned directly underneath it, with a non-existing gap between them. To initiate the scrolling, texture A is being displaced vertically by an arbitrary number of pixels, and texture B follows it at the same pace. As texture B reaches the zero point (top of the viewport), texture A is no longer visible, therefore it is displaced vertically to be below texture B. This cycle can be repeated as many times as necessary during gameplay as well as while the user is in the menu.

Let’s take a look at the code that makes it possible, starting with the main menu screen:

First of all, you need to be aware that every game screen is automatically inheriting the properties and capabilities of base class GameScreenBase. This is the class the offers the foundation both for basic texture loading and movement:

protected private:
    // Core background textures
    Microsoft::WRL::ComPtr<ID3D11Texture2D>                    m_backgroundBlockA;
    Microsoft::WRL::ComPtr<ID3D11Texture2D>                    m_backgroundBlockB;

void MoveBackground(float velocity);

It also offers the core texture containers for the overlaid elements that are present in most screens, such as clouds:

// Overlayed clouds
Microsoft::WRL::ComPtr<ID3D11Texture2D> m_overlayA;
Microsoft::WRL::ComPtr<ID3D11Texture2D> m_overlayB;

The overlay movement is inherently dependent on the base background displacement and can be adjusted relative to the initial velocity. Let’s take a look at GameScreenBase.cpp, specifically at MoveBackground:

void GameScreenBase::MoveBackground(float velocity)
{
    if (m_backgroundPositionA <= -BACKGROUND_MIDPOINT)
        m_backgroundPositionA = m_backgroundPositionB + (BACKGROUND_MIDPOINT * 2);

    if (m_backgroundPositionB <= -BACKGROUND_MIDPOINT)
        m_backgroundPositionB = m_backgroundPositionA + (BACKGROUND_MIDPOINT * 2);

    m_backgroundPositionA -= velocity;
    m_backgroundPositionB -= velocity;
}

The BACKGROUND_MIDPOINT value is relative to the height of the background texture. As we are working with a variable screen size, given that tablets and desktops do not have the same resolution, the movement has to be adjusted accordingly. One way, however, to ensure the proper texture positioning would be to place it in relation to its previous instance. Hence, this snippet in UpdateWindowSize:

BACKGROUND_MIDPOINT = 1366.0f / 2.0f;
m_backgroundPositionA = BACKGROUND_MIDPOINT;
m_backgroundPositionB = m_backgroundPositionA * 3;

Because overlays are not necessarily a part of every screen, I am not including the MoveOverlay method in the base class. Let’s now take a look at MenuScreen.cpp. Take a look at the Load method and you will see several lines that prepare the background and overlays:

m_loader = ref new BasicLoader(Manager->m_d3dDevice.Get(), Manager->m_wicFactory.Get());

m_loader->LoadTexture("Assets\\Backgrounds\\generic_blue_a.png", &m_backgroundBlockA, nullptr);
m_loader->LoadTexture("Assets\\Backgrounds\\generic_blue_b.png", &m_backgroundBlockB, nullptr);
m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_a.png", &m_overlayA, nullptr);
m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_b.png", &m_overlayB, nullptr);

CurrentSpriteBatch->AddTexture(m_backgroundBlockA.Get());
CurrentSpriteBatch->AddTexture(m_backgroundBlockB.Get());
CurrentSpriteBatch->AddTexture(m_overlayA.Get());
CurrentSpriteBatch->AddTexture(m_overlayB.Get());

The BasicLoader class was imported from the Direct3D sprite sample. A call to LoadTexture will read the data from a DDS or PNG file and output the data in an ID3D11Texture2D object. Once loaded, the texture is added to the SpriteBatch instance associated with the screen, also declared as a part of GameScreenBase.

Depending on the screen, this procedure might have to be done for multiple textures, as you will see later in this article. Each page also has two timed loops—RenderScreen and Update. RenderScreen is responsible for taking everything from the SpriteBatch instance and showing it to the user. If you’ve used the XNA SpriteBatch before, you are aware that you need to start the drawing cycle by calling Begin and end it by calling End. The same applies here:

CurrentSpriteBatch->Begin();

CurrentSpriteBatch->Draw(
    m_backgroundBlockA.Get(),
    float2(Manager->m_windowBounds.Width / 2, m_backgroundPositionA),
    PositionUnits::DIPs,
    m_screenSize,
    SizeUnits::Pixels);

CurrentSpriteBatch->Draw(
    m_backgroundBlockB.Get(),
    float2(Manager->m_windowBounds.Width / 2 ,m_backgroundPositionB),
    PositionUnits::DIPs,
    m_screenSize,
    SizeUnits::Pixels);

if (m_showBear->IsLoaded)
    m_showBear->Render();

if (m_showMonster->IsLoaded)
    m_showMonster->Render();

CurrentSpriteBatch->Draw(
    m_overlayA.Get(),
    float2(Manager->m_windowBounds.Width/2, m_backgroundPositionA),
    PositionUnits::DIPs,
    m_screenSize,
    SizeUnits::Pixels);

CurrentSpriteBatch->Draw(
    m_overlayB.Get(),
    float2(Manager->m_windowBounds.Width / 2 ,m_backgroundPositionB),
    PositionUnits::DIPs,
    m_screenSize,
    SizeUnits::Pixels);

CurrentSpriteBatch->End();

The current overloaded Draw call gets the following items:

• The texture object
• The position where the object has to be drawn on the screen
• The way the object is positioned (can also be a normalized value or a pixel value)
• The size of the texture (stretching may occur)
• The type of the size value (in this case, I am using pixels, but can also be normalized)

The order in which the Draw calls are arranged determines the order of objects drawn on the screen. The calls on top will place texture objects at the bottom of the rendering stack, and the calls at the end will place the objects at the top of the stack.

The Gameplay Screen Background & Overlays

Let’s move on to the arguably most critical screen in the project, GamePlayScreen.cpp. There are a few nuances that differentiate it from any other screen—in particular, the background loading routine.

For every game, there is a different level type that is being used. With each level type, there is a different combination of a background and the overlay. Currently, there are four supported level types:

• Space
• Nightmare
• Magic Bean
• Dream

When the proper level is detected and the metadata is loaded from the associated XML file (more about this process later on in the series), the level textures are loaded into memory:

switch (m_currentLevelType)
{
    case LevelType::SPACE:
    {
        m_loader->LoadTexture("Assets\\Backgrounds\\generic_dark_blue_a.png", &m_backgroundBlockA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\generic_dark_blue_b.png", &m_backgroundBlockB, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\star_overlay_a.png", &m_overlayA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\star_overlay_b.png", &m_overlayB, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\galaxy_overlay_a.png", &m_overlayGalaxyA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\galaxy_overlay_b.png", &m_overlayGalaxyB, nullptr);
        
        CurrentSpriteBatch->AddTexture(m_overlayGalaxyA.Get());
        CurrentSpriteBatch->AddTexture(m_overlayGalaxyB.Get());
        break;
    }
    case LevelType::NIGHTMARE:
    {
        m_loader->LoadTexture("Assets\\Backgrounds\\generic_red_a.png", &m_backgroundBlockA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\generic_red_b.png", &m_backgroundBlockB, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_a.png", &m_overlayA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_b.png", &m_overlayB, nullptr);
        break;
    }
    case LevelType::MAGIC_BEANS:
    {
        m_loader->LoadTexture("Assets\\Backgrounds\\generic_blue_a.png", &m_backgroundBlockA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\generic_blue_b.png", &m_backgroundBlockB, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_a.png", &m_overlayA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_b.png", &m_overlayB, nullptr);
        
        break;
    }
    case LevelType::DREAM:
    {
        m_loader->LoadTexture("DDS\\Levels\\Dream\\TEST_backgroundDream_01.dds", &m_backgroundBlockA, nullptr);
        m_loader->LoadTexture("DDS\\Levels\\Dream\\TEST_backgroundDream_02.dds", &m_backgroundBlockB, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_a.png", &m_overlayA, nullptr);
        m_loader->LoadTexture("Assets\\Backgrounds\\cloud_overlay_b.png", &m_overlayB, nullptr);
        break;
    }
}

This way, no unnecessary textures are loaded. A screen-based level flag allows me to control the incoming assets. At this point, the level environment does not change dynamically, so it is safe to assume that the textures should be loaded on a per-level basis.

The RenderScreen method is called in the same manner as in the menu screen, with the moving background and overlays located at the bottom of the rendering stack:

CurrentSpriteBatch->Draw(
    m_backgroundBlockA.Get(),
    float2(Manager->m_windowBounds.Width / 2, m_backgroundPositionA),
    PositionUnits::DIPs,
    m_screenSize,
    SizeUnits::Pixels);

CurrentSpriteBatch->Draw(
    m_backgroundBlockB.Get(),
    float2(Manager->m_windowBounds.Width / 2, m_backgroundPositionB),
    PositionUnits::DIPs,
    m_screenSize,
    SizeUnits::Pixels);

CurrentSpriteBatch->Draw(
    m_overlayA.Get(),
    float2(Manager->m_windowBounds.Width / 2, m_overlayPositionA),
    PositionUnits::DIPs,
    float2(768.0f, 1366.0f),
    SizeUnits::Pixels);

CurrentSpriteBatch->Draw(
    m_overlayB.Get(),
    float2(Manager->m_windowBounds.Width / 2, m_overlayPositionB),
    PositionUnits::DIPs,
    float2(768.0f, 1366.0f),
    SizeUnits::Pixels);

Character Movement

As you are now aware of the basic screen structure and how the basic rendering process is built, let’s take a look at how the main game character moves on the screen. Falling down, the teddy bear also needs to move left and right to ensure that he is able to pick up power-ups and buttons as well as avoid obstacles and enemy ammo.

There are several important considerations here. The most important one is to not assume that the user will have a specific input device. Potential movement controllers include a keyboard, the mouse, the touch screen and the accelerometer. In the most common scenarios, the desktop machines will not have an accelerometer, and the tablet computers will not have a constantly attached keyboard and a mouse. In FallFury, I decided to leverage all potential input engines and let the user choose the best option for himself.

When the current GamePlayScreen instance loads, I am attempting to get access to the system accelerometer device:

m_systemAccelerometer = Windows::Devices::Sensors::Accelerometer::GetDefault();

m_systemAccelerometer is of type Windows::Devices::Sensors::Accelerometer and is declared in GamePlayScreen.h. If an accelerometer is detected, I need to bind it to a ReadingChanged event handler that will give me the current G-force transformed into X, Y, and Z displacement:

if (m_systemAccelerometer != nullptr)
{
    m_systemAccelerometer->ReadingChanged += ref new TypedEventHandler<Accelerometer^, AccelerometerReadingChangedEventArgs^>
            (this, &GamePlayScreen::AccelerometerReadingChanged);
}

ReadingChanged itself does not participate in updating the position for the character, but rather passes the current values to m_xAcceleration, which is later used in the Update method:

void GamePlayScreen::AccelerometerReadingChanged(_In_ Accelerometer^ accelerometer, _In_ AccelerometerReadingChangedEventArgs^ args)
{
    if (StaticDataHelper::IsAccelerometerEnabled)
    {
        auto currentOrientation = DisplayProperties::CurrentOrientation;
        float accelValue;
        
        if (currentOrientation == DisplayOrientations::Portrait)
                    accelValue = args->Reading->AccelerationY;
        else if (currentOrientation == DisplayOrientations::PortraitFlipped)
                    accelValue = -args->Reading->AccelerationY;
        else if (currentOrientation == DisplayOrientations::Landscape)
                    accelValue = args->Reading->AccelerationX;
        else if (currentOrientation == DisplayOrientations::LandscapeFlipped)
                    accelValue = -args->Reading->AccelerationX;
        else
                    accelValue = 0.0f;
        
        if (StaticDataHelper::IsAccelerometerInverted)
                    m_xAcceleration = -accelValue;
        else
                    m_xAcceleration = accelValue;
    }
}

The reason for this lies in the fact that ReadingChanged is triggered at a much lower rate than the Update loop. If the character position would be adjusted through the core accelerometer event handler, the result would be choppy (“step-by-step”) movement instead of a smooth transition.

Notice, also, that depending on the screen orientation, I need to get the acceleration either on the X- or Y-axes. Since an accelerometer is detected, I am assuming that the device that’s being used is a tablet. Therefore, it can have auto-rotate enabled, which means that the reference axis (horizontal) might change depending on how the user holds the device. DisplayProperties::CurrentOrientation can give me the current orientation, whether portrait (Y acceleration value) or landscape (X acceleration value):

As with many other titles, the user may invert the movement based on the accelerometer reading. For example, if the device is tilted to the right, the character will move to the left, and vice-versa. The effect is easily achieved by negating the current reading, regardless of the axis it is relying on.

Obviously, as the character moves, there should be boundaries that restrict the movement within the context of the current game screen. To get the correct screen bounds, GameScreenBase, the foundation class for every screen, sets four properties: LoBoundX, HiBoundX, LoBoundY and HiBoundY:

LoBoundX = (rWidth - 768.0f) / 2.0f;
HiBoundX = LoBoundX + 768.0f;

LoBoundY = 0;
HiBoundY = LoBoundY + rHeight;

LoBoundX is the leftmost limit for the horizontal playable area and HiBoundX is the rightmost limit for the same horizontal area. LoBoundY and HiBoundY are responsible for carrying the limits for the vertical space. All four boundary values are relative to the screen size:

To consistently get the correct X boundary no matter the screen size, the playable area is set to a fixed width of 768 pixels. The rest of the screen is accordingly cancelled out and the remaining area split in two. The original X point (zero) is added to the curtain size and that way there is the leftmost X boundary. The Y boundaries are simply obtained from the screen height, as there are no gameplay experience restrictions in that domain.

The bear position is updated in the Update loop in the game screen. There are several parameters that need to be adjusted, such as the vertical velocity, the bear rotation on tilt and the horizontal displacement.

When the level just starts, the bear falls faster until he reaches the standard static Y point. Because of screen size differences, this should not be done by comparing the pixel distance but rather by utilizing a ratio built from the current bear Y position and the high Y boundary:

if ((GameBear->Position.y / HiBoundY) < 0.19f)
{
    GameBear->Position.y += GameBear->Velocity.y * (3.2f);
}

Assuming that the game is not paused, and thus the background is moving, the bear Y position should be adjusted relative to the current velocity set for the background scrolling. Because of how parallax scrolling works, the bear velocity has to be higher than the initial screen movement. Therefore, it is multiplied by a fixed value independent of the level played:

if (!m_isBackgroundMoving)
{
    if (GameBear->Position.y > m_screenSize.y)
    {
        Manager->CurrentGameState = GameState::GS_GAME_OVER;
    }
    else
    {
        GameBear->Position.y += GameBear->Velocity.y * 1.5f;
    }
}

In the statement above, there is also an extra condition that verifies whether the bear is below the low Y boundary. If it is, then the game is over. This is imposed by a game animation that takes the bear off the Y limits, meaning that the bear is dead.

Bear rotation is based on the current X acceleration, but the bear shouldn’t rotate 360 degrees. To limit the rotation, there is a rotation threshold set (value taken in radians) that is being checked before rotating the character:

float compositeRotation = GameBear->Rotation - (float)m_xAcceleration / 10.0f;
if (compositeRotation < m_rotationThreshold && compositeRotation > -m_rotationThreshold)
    GameBear->Rotation = compositeRotation;

The composite value lets me verify the perspective rotation without actually assigning it to the bear. If it is within the imposed threshold, only then will the bear rotation be adjusted.

Using the composite value approach is also efficient when performing the horizontal displacement adjustment. The initial value is composed of the current position and the X-based acceleration multiplied by a dynamic multiplier value to create the inertia effect:

float compositePosition = GameBear->Position.x + ((float)m_xAcceleration * m_accelerationMultiplier);

if (m_xAcceleration < 0)
    compositePosition -= 100.0f;
else
    compositePosition += 100.0f;

if (Manager->IsWithinScreenBoundaries(float2(compositePosition, GameBear->Position.y)))
{
    GameBear->Position.x += (float)m_xAcceleration * m_accelerationMultiplier;
}
else
{
    if (GameBear->Position.x > HiBoundX)
    {
        GameBear->Position.x = HiBoundX - 180.0f;
    }
    else if (GameBear->Position.x < LoBoundX)
    {
        GameBear->Position.x = LoBoundX + 180.0f;
    }
}

If the bear is attempting to hit a “wall” (screen limit), its position is set back to the one barely prior to the limit. By doing this, I am avoiding locking the character on the side of the screen.

There is something in this snippet above that you might not be aware of—a reference to Manager->IsWithinScreenBoundaries. This method belongs to the ScreenManager (ScreenManager.cpp) class—a utility class that ensures the proper screen is displayed depending on the current game mode, and also allows control of mouse actions and boundary checks:

bool ScreenManager::IsWithinScreenBoundaries(float2 position)
{
    if (position.x < CurrentGameScreen->LoBoundX || position.x > CurrentGameScreen->HiBoundX || position.y < CurrentGameScreen->LoBoundY || position.y > CurrentGameScreen->HiBoundY)
            return false;
    else
            return true;
}

You saw how the movement is accomplished with the help of the accelerometer. Let’s take a look at how a keyboard can be used to do the same thing. There is a HandleKeyInput method, exposed through the GamePlayScreen class. As a matter of fact, HandleKeyInput is wired into the GameScreenBase class, therefore if a specific combination needs to be handled outside the context of the game play screen, it can be:

void GamePlayScreen::HandleKeyInput(Windows::System::VirtualKey key)
{
    if (key == Windows::System::VirtualKey::Right)
    {
        if (GameBear->IsWithinScreenBoundaries(GameBear->Size.x, 0.0f, GetScreenBounds()))
        {
            GameBear->Direction = TurningState::RIGHT;
            
            m_xAcceleration = 0.8f;
            
            if (GameBear->Rotation >= -m_rotationThreshold)
                            GameBear->Rotation -= 0.02f;
        }
    }
    else if (key == Windows::System::VirtualKey::Left)
    {
        if (GameBear->IsWithinScreenBoundaries(-GameBear->Size.x, 0.0f, GetScreenBounds()))
        {
            GameBear->Direction = TurningState::LEFT;
            
            m_xAcceleration = -0.8f;
            
            if (GameBear->Rotation <= m_rotationThreshold)
                            GameBear->Rotation += 0.02f;
        }
    }
}

As the accelerometer is no longer influencing the rotation or displacement, both indicators have to be manipulated through key presses. There are still standard thresholds in place to limit the potential incorrect movement, but the idea remains the same. This method is being called from the XAML page, which is overlaid on top of the DirectX renders:

<SwapChainBackgroundPanel
    x:Class="Coding4Fun.FallFury.DirectXPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:Coding4Fun.FallFury" x:Name="XAMLPage"
    xmlns:controls="using:Coding4Fun.FallFury.Controls"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d" Loaded="OnLoaded" KeyDown="OnKeyDown" LayoutUpdated="XAMLPage_LayoutUpdated">

void DirectXPage::OnKeyDown(Platform::Object^ sender, Windows::UI::Xaml::Input::KeyRoutedEventArgs^ e)
{
    m_renderer->CurrentGameScreen->HandleKeyInput(e->Key);
}

When the keyboard is not available, movement can be controlled with the help of a mouse. Again, with standard event handlers, I am simply using OnPointerMoved:

void GamePlayScreen::OnPointerMoved(Windows::UI::Core::PointerEventArgs^ args)
{
    if (StaticDataHelper::IsMouseEnabled)
    {
        if (GameBear != nullptr)
        {
            m_touchCounter++;
            if (GameBear->IsWithinScreenBoundaries(GameBear->Size.x, 0.0f, GetScreenBounds()))
            {
                m_xAcceleration = (args->CurrentPoint->RawPosition.X - GameBear->Position.x) / m_screenSize.x;
            }
        }
    }
}

By using this method, the bear will accelerate to the point where the mouse cursor is located, having a higher velocity the further it is located from the cursor. Once again, this creates the inertia visualization.

Conclusion

Concluding Part 3 of the series, remember that because Windows 8 is not a tablet-only OS, some users might have different input devices. Try to accommodate as many of those as possible.

The next article in this series will focus on the XAML overlay used in FallFury.

FallFury not only relies on standard C++/C# and XAML code, but also on shaders. This article is intended for developers who are not aware of what shaders are and want to know how to use them in their projects. I will talk about creating shaders, as well as the shaders used in my project.

Check out the video for this article at http://channel9.msdn.com/Series/FallFury/Part-2-Shaders.  For a complete, offline version of this series, you may download a nicely formatted PDF of all the articles.

Code on GPU

In simple terms, shaders are small programs that are executed on the Graphical Processing Unit (GPU) instead of the Central Processing Unit (CPU). In recent years, we’ve seen a major spike in the capabilities of graphic devices, allowing hardware manufacturers to design an execution layer tied to the GPU, therefore being able to target device-specific manipulations to a highly optimized unit. Shaders are not used for simple calculations, but rather for image processing. For example, a shader can be used to adjust image lighting or colors.

Modern GPUs give access to the rendering pipeline that allows developers to execute arbitrary image processing code. This is a step forward from a fixed-function pipeline that was present in older GPUs, where image processing tasks were integrated into the hardware unit and were only able to perform a limited set of actions, such as transforms. Unlike the rendering pipeline, the fixed-function pipeline was not programmable, therefore the developers were often tied to the hardware they used for offering specific game effects, in some cases having to resort to software-based adjustments.

Types of Shaders

There are different types of image manipulations that can be performed on a given input, and so there are different types of shaders designed to handle that. Currently, we can highlight three main shader types:

• Vertex shaders – because what the user sees on the screen is not really three-dimensional, but rather a three-dimensional simulation in a 2D space, vertex shaders translate the coordinates of a vector in 3D space in relation to the 2D frame. Vertex shaders are executed one time per vector passed to the GPU. Typically, vectors carry data related to their position and the coordinate of the bound texture as well as color. A vertex shader is able to manipulate all these properties, but there is never a situation where a new vertex is created as a result of the execution.
• Pixel shaders – these programs are executed on the GPU in relation to every passed pixel, working on a much lower level. For example, if you want specific pixels adjusted for lighting or 3D bump mapping, a pixel shader can provide the desired effect for a surface. Rarely, there are situations where only a few pixels should be re-adjusted at once. Pixel shaders are often run with an input of millions of pixels, resulting in complex effects.
• Geometry shaders – these shaders are the next progression from vertex shaders, introduced with DirectX 10. The developer is able to pass specific primitives as input and either have the output represent the modified version of what was passed to the program or have new primitives, such as triangles, be generated as a result. Geometry shaders are always executed on post-vertex processing in the rendering pipeline. When vertex shader execution is completed, geometry shaders step in, if present. Geometry shaders can be used to refine the level of detail of a specific object. For example, when an object is closer or further away from the viewport camera, the mesh would have to be refined to minimize the rendering load.

FallFury uses all these shader types as a part of the game.

Enough Talk, Let’s Code

Now that you are aware of what shaders are, let’s write some sample code and test it. It is worth mentioning that shaders are not written in a standard high-level language, but rather in a language defined by the environment the shader is used in. For Direct3D, this is the High-Level Shader Language, or HLSL. It is somewhat similar to C, but with some specific nuances.

Start by creating a test Direct3D Windows Store application:

If you create and run this sample application, you will see that the output of it is a simple 3D spinning cube:

You probably also noticed that there are two shaders that are a component part of the newly created solution: SimplePixelShader.hlsl and SimpleVertexShader.hlsl. Take a look inside the pixel shader:

struct PixelShaderInput
{
    float4 pos : SV_POSITION;
    float3 color : COLOR0;
};

float4 main(PixelShaderInput input) : SV_TARGET
{
    return float4(input.color,1.0f);
}

First of all, there is a PixelShaderInput struct[DW1] . It represents a single pixel – it has a float4 field that represents the position of the pixel and a float3 field that represents the RGB pixel color. The field itself is also marked by a predefined type, such as SV_POSITION or COLOR. This is a string that determines the use of the field. You can read more about the shader semantics here.

The strings that are prefixed with SV_ are representing system-value semantics. Those have special meaning in the pipeline during the processing stages. In the pixel shader above, SV_POSITION will always mean the pixel position.

Look at what is being returned from the pixel shader—instead of the standard float3 color indicator, you are now returning a float4, which couples the existing value, input.color, with a 1.0f float value that represents the alpha-channel value. Remember, that inside shaders the color is clamped between 0 and 1 instead of the standard 255-value limit.

Since the cube rendering mechanism is already in place, let’s experiment with the pixel shader a bit. You’ve already got the float4 color representation:

You can set any of these values to 1.0 to return the solid color, so let’s do that. Let’s render the cube green. Modify the return statement to be this:

return float4(0.0, 1.0, 0.0, 1.0);

At this point, if you will run the program you will get a rendering very similar to this:

This is a good start.. Now, let’s now take a look at the vertex shader in the project. By default, you get this:

cbuffer ModelViewProjectionConstantBuffer : register(b0)
{
    matrix model;
    matrix view;
    matrix projection;
};

struct VertexShaderInput
{
    float3 pos : POSITION;
    float3 color : COLOR0;
};

struct VertexShaderOutput
{
    float4 pos : SV_POSITION;
    float3 color : COLOR0;
};

VertexShaderOutput main(VertexShaderInput input)
{
    VertexShaderOutput output;
    float4 pos = float4(input.pos, 1.0f);
    
    pos = mul(pos, model);
    pos = mul(pos, view);
    pos = mul(pos, projection);
    output.pos = pos;
    
    // Pass through the color without modification.
    output.color = input.color;
    
    return output;
}

There are a couple of differences here compared to the above mentioned pixel shader:

• cbuffer ModelViewProjectionConstantBuffer – represents a constant buffer that contains three matrices, to which vertices are related—the model, view and projection matrices. Constant buffers are interesting structures that have been optimized to allow block-wise updates, where multiple constants are grouped in one boxed unit and can be updated simultaneously instead of having a one-by-one iterative update cycle.
• struct VertexShaderInput – vertices are passed one-by-one to the shader, and this specific structure represents the input. Notice that it carries the 3D representation of the vertex position as well as its RGB color value.
• struct VertexShaderOutput – the final processed output, which now carries the position in relation to all three matrices mentioned above as well as the processed color. Notice that the fourth value is the camera distance in the demo.
• VertexShaderOutput main(VertexShaderInput input) – this is the main function that performs the vertex processing. Initially, it performs the position adjustment relative to the camera and then uses mul, a built-in function that multiplies matrices, to represent the current vertices in the projected space.

So let’s play around with what we have in stock. Take a look at the main function and how initially, the float3-based position is transformed to contain the camera distance:

float4 pos = float4(input.pos, 1.0f);

This position is normalized in relation to the current viewport. Afterwards, the vertex is transformed in the current 3D space (relative to three matrices – model, view, and projection):

pos = mul(pos, model);
pos = mul(pos, view);

pos = mul(pos, projection);

output.pos = pos;

As with the pixel shader, these are some very basic manipulations. Let’s flip the cube upside-down. To do this, we need to apply a rotation transformation. Here is an interesting piece of advice—when working with manipulations in shaders, make sure that you know basic matrix operations.

For example, to perform a simple 2D rotation, you need to use the rotation matrix:

But since we’re in 3D space, we not only have the X and Y coordinates, which relate to the matrix above, but also the Z coordinate. Therefore, a different method should be applied. There are three fundamental matrices that can be used to rotate an object around the three possible axes:

For now, we want to rotate the cube along the X-axis. To do this, inside the main function, we need to declare a constant that represents the rotation angle, in radians:

const float angle = 1.3962634;

Looking at the matrix above, we need to find out the sine and cosine of the given angle. When working with vertex shaders, HLSL offers a built-in function, called sincos that is able to get both values from an input value:

float cosLength, sinLength;
sincos(angle, sinLength, cosLength);

Now you need to declare the rotation matrix. Again, HLSL comes with some built-in capabilities to declare matrices and set their values:

float3x3 xAxisRotation = { 
    1.0, 0.0, 0.0, // Row 1
    0, cosLength, -sinLength, // Row 2
    0, sinLength, cosLength}; // Row 3

The standard format for matrix declaration in this case follows the following pattern:

Matrix<type,size> localName

For matrix multiplication, we can once again leverage the mul function:

float3 temporaryPosition;
temporaryPosition = mul(input.pos,xAxisRotation);

Now we can normalize the position to a float4 value that also includes the camera distance:

float4 pos = float4(temporaryPosition, 1.0f);

The rest of the transformation procedures can be taken directly from the original shader, multiplying the float4 position by the model, view, and projection matrices. Your entire main function should now look like this:

VertexShaderOutput main(VertexShaderInput input)
{
    VertexShaderOutput output;

    const float angle = 1.3962634;
    float cosLength, sinLength;
    sincos(angle, sinLength, cosLength);

    float3x3 xAxisRotation = { 
        1.0, 0.0, 0.0, // Row 1
        0, cosLength, -sinLength, // Row 2
        0, sinLength, cosLength}; // Row 3

    float3 temporaryPosition;
    temporaryPosition = mul(input.pos,xAxisRotation);
    float4 pos = float4(temporaryPosition, 1.0f);

    // Transform the vertex position into projected space.
    pos = mul(pos, model);
    pos = mul(pos, view);
    pos = mul(pos, projection);
    output.pos = pos;

    // Pass through the color without modification.
    output.color = input.color;

    return output;
}

The current angle is set to 80 degrees, or 1.3962634 radians. If you run the rendering test application, the result you will get will be similar to this:

Now, let’s look at how shaders are handled on the DirectX side.

Shaders in DirectX

Open CubeRenderer.cpp. This is the source file where internal shaders are read and passed to the device to be executed. Notice one interesting aspect of the process – the shader file contents are being read first and then passed to m_d3dDevice->CreateVertexShader. m_d3dDevice is a pointer to a virtual adapter that can be used to create device-specific resources. CreateVertexShader creates a vertex shader from an already compiled shader. You can notice it from the fact that the data is read not from the initial .hlsl file, but rather from the .cso (Compiled Shader Object):

auto loadVSTask = DX::ReadDataAsync("SimpleVertexShader.cso");

As with any program, before it is passed onto the execution layer, it has to be compiled first. Visual Studio 2012 comes with a bundled HLSL compiler, fxc—the Effect Compiler Tool. The default behavior for a shader is to be compiled with the .cso file extension in the same output directory as the project, but this can be changed by setting the Object File Name in the shader properties:

You can read more about the shader compilation process here.

Looking back at the sample vertex shader that was created as a part of the project, you will notice that there is a specific input layout set for the incoming object:

struct VertexShaderInput
{
    float3 pos : POSITION;
    float3 color : COLOR0;
};

The virtual adapter is not aware of the structure layout. Therefore, the developer needs to explicitly create an internal D3D11_INPUT_ELEMENT_DESC array that will contain the type of information passed to the shader:

const D3D11_INPUT_ELEMENT_DESC vertexDesc[] = 
{
    { 
        "POSITION", 
        0, 
        DXGI_FORMAT_R32G32B32_FLOAT, 
        0, 
        0, 
        D3D11_INPUT_PER_VERTEX_DATA, 
        0 },
    {
        "COLOR", 
        0, 
        DXGI_FORMAT_R32G32B32_FLOAT, 
        0, 
        12, 
        D3D11_INPUT_PER_VERTEX_DATA, 
        0 },
};

Once the description is complete, the input needs to be assembled for processing. That’s where CreateInputLayout comes into play:

DX::ThrowIfFailed(
    m_d3dDevice->CreateInputLayout(
        vertexDesc,
        ARRAYSIZE(vertexDesc),
        fileData->Data,
        fileData->Length,
        &m_inputLayout
        )
    );

You are basically passing a shader signature to the input assembler that will perform all the consequent processing. A similar process is applied for the existing pixel shader, with the main difference being the fact that instead of CreateVertexShader, CreatePixelShader is called:

Passing Custom Parameters to Shaders

Going back to our vertex shader where we performed the rotation relative to the X-axis, you probably noticed that the angle is hard-coded and is applied to each vector in the same way. This is rarely the case, as the angle would normally come from inside the game itself, often responding to internal behavior, such as character movement or action.

To pass a parameter to the shader, you need to first of all redefine the input structure. Let’s add an angle carrier to the VertexShaderInput struct in SimpleVertexShader.hlsl:

struct VertexShaderInput
{
    float3 pos : POSITION;
    float3 color : COLOR0;
    float angle : TRANSFORM0;
};

This alone won’t do anything. Go the entry point function (main) and make sure that the angle constant is set to input.angle:

const float angle = input.angle;

Now the shader is ready, but you also need to let your game know that the vertex shader has a modified input layout. To do this, go to CubeRenderer.cpp and find the D3D11_INPUT_ELEMENT_DESC array that defines the input layout for incoming vertex shaders. Simply add an identifying item to the existing array:

const D3D11_INPUT_ELEMENT_DESC vertexDesc[] = 
{ 
    { "POSITION", 0, DXGI_FORMAT_R32G32B32_FLOAT, 0, 0, D3D11_INPUT_PER_VERTEX_DATA, 0 }, 
    { "COLOR", 0, DXGI_FORMAT_R32G32B32_FLOAT, 0, 12, D3D11_INPUT_PER_VERTEX_DATA, 0 }, 
    { "TRANSFORM", 0, DXGI_FORMAT_R32_FLOAT, 0, 24, D3D11_INPUT_PER_VERTEX_DATA, 0 } 
};

The first parameter is the pre-defined semantic used in the shader. The second parameter defines the input index. After that, use DXGI_FORMAT_R32_FLOAT to indicate that the value passed will be a standard float. Pay close attention when you specify the input offset. Notice that the two FLOAT3 values, POSITION and COLOR, take 12 bytes each —a float takes 32 bits (4 bytes), and you have a triplet, therefore the offset for TRANSFORM should be 24 bytes (two times 12 bytes from previous indicators).

Now you need to modify the internal vector descriptors that are being passed to the rendering pipe. In the sample project those are created with the help of the VertexPositionColor class, located in the CubeRenderer.h. Add a simple float field to the existing struct, so it looks like this:

struct VertexPositionColor 
{ 
    DirectX::XMFLOAT3 pos; 
    DirectX::XMFLOAT3 color; 
    float angle; 
};

In CubeRenderer.cpp, find the cubeVerticles array. For each created VertexPositionColor you are now able to add a third value representing the rotation:

auto createCubeTask = (createPSTask && createVSTask).then([this] () { 
    VertexPositionColor cubeVertices[] = 
    { 
        {XMFLOAT3(-0.5f, -0.5f, -0.5f), XMFLOAT3(0.0f, 0.0f, 0.0f), 1.38f}, 
        {XMFLOAT3(-0.5f, -0.5f, 0.5f), XMFLOAT3(0.0f, 0.0f, 1.0f), 1.38f}, 
        {XMFLOAT3(-0.5f, 0.5f, -0.5f), XMFLOAT3(0.0f, 1.0f, 0.0f), 1.38f}, 
        {XMFLOAT3(-0.5f, 0.5f, 0.5f), XMFLOAT3(0.0f, 1.0f, 1.0f), 1.38f}, 
        {XMFLOAT3( 0.5f, -0.5f, -0.5f), XMFLOAT3(1.0f, 0.0f, 0.0f), 1.38f}, 
        {XMFLOAT3( 0.5f, -0.5f, 0.5f), XMFLOAT3(1.0f, 0.0f, 1.0f), 1.38f}, 
        {XMFLOAT3( 0.5f, 0.5f, -0.5f), XMFLOAT3(1.0f, 1.0f, 0.0f), 1.38f}, 
        {XMFLOAT3( 0.5f, 0.5f, 0.5f), XMFLOAT3(1.0f, 1.0f, 1.0f), 1.38f}, 
    };

Now you will be able to pass parameters to the vertex shader without having to manually modify the shader itself.

Shaders in FallFury

There are several shaders used in FallFury, which must be selected depending on the Direct3D feature level available on the machine. A feature level determines what a video adapter can do in terms of rendering—even though Direct3D is a unified framework, it still heavily relies on how individual graphic cards can perform.

There are 5 shaders used internally for texture rendering. Specifically, there is a pixel shader, a replication vertex shader, an instancing vertex shader and geometry shaders. This could be familiar if you worked with Microsoft DirectX sprite samples before:

Given the platform limitations, geometry shaders can only be used on devices supporting Direct3D Feature Level 10. When FallFury detects that the feature level is lower than that, it has to fall back on either the instancing or the replication shaders. Some devices, such as the Microsoft Surface, are at feature level 9.1. Therefore, the replication render technique must be enforced.

Following the Microsoft DirectX Sprite Sample, it is fairly easy to simply select the correct render technique once the feature level is detected with GetFeatureLevel:

auto featureLevel = m_d3dDevice->GetFeatureLevel(); 
if (featureLevel >= D3D_FEATURE_LEVEL_10_0) 
{ 
    m_technique = RenderTechnique::GeometryShader; 
} 
else if (featureLevel >= D3D_FEATURE_LEVEL_9_3) 
{ 
    m_technique = RenderTechnique::Instancing; 
} 
else 
{ 
    m_technique = RenderTechnique::Replication; 
    if (capacity > static_cast<int>(Parameters::MaximumCapacityCompatible)) 
    { 
        // The index buffer format for feature-level 9.1 devices may only be 16 bits. 
        // With 4 vertices per sprite, this allows a maximum of (1 << 16) / 4 sprites. 
        throw ref new Platform::InvalidArgumentException(); 
    } 
}

Depending on the selected render technique, which is determined on application startup, the proper input layout is selected for each shader and is used to control the rendering pipe.

Different graphic adapters also support different shader models. You need to account for those, and before running the application, the HLSL compiler will take on the task of determining whether a proper shader component is supported by the given model. In the shader properties, make sure that you specify the used shader model, as well as the type of the shader:

Without this, you are bound to experience compile time errors that will prevent you from launching the application or deploying it to different devices.

Conclusion

Shaders are not an easy subject. I highly recommend reading The Cg Tutorial, published online for free by nVidia. Even though it describes the Cg shader language, it is virtually identical to HLSL and you will not have any problems using the practices you learned there in building HLSL shaders.