PlayStation Mobile Development Cookbook

You need to have a Sony Entertainment Network (SEN) account to register with the PSM portal. This is the standard account you use to bring your PlayStation device online, so you may already have one. If not, create one at http://bit.ly/Yiglfk before continuing.

A PlayStation Mobile account is mandatory to download the PSM tools. Many of the links to the portal require you to be logged in before they will work. It is very important that you create and activate your account and log in to the portal before continuing on with the book! All future recipes assume you are logged in to the portal.

First you need to download the PlayStation Mobile SDK; you can download it from http://bit.ly/W8rhhx.

The SDK is now installed on your machines. Assuming you used default directories, the SDK will be installed to C:\Program Files (x86)\SCE\PSM if you are running 64 bit Windows, or to C:\Program Files\SCE\PSM if you are running 32 bit Windows. Additionally all of the documentation and samples have been installed under the Public account, located in C:\Users\Public\Documents\PSM .

There are a number of samples available in the samples directory and you should certainly take a moment to check them out. They range in complexity from simple Hello World applications, up to a full blown 3rd person 3D role playing game (RPG). They are, however, often documented in Japanese and often rely on other samples, making learning from them a frustrating experience at times, at least, for those of us who do not understand Japanese!

From the start menu, locate and launch PSM Studio in the PlayStation Mobile folder.

Not much to look at, but it's your first running PlayStation Mobile application! Now let's take a quick look at the code it generated:

using System;
using System.Collections.Generic;
using Sce.PlayStation.Core;
using Sce.PlayStation.Core.Environment;
using Sce.PlayStation.Core.Graphics;
using Sce.PlayStation.Core.Input;

namespace Ch1_Example1
{
  public class AppMain{
    private static GraphicsContext graphics;

    public static void Main (string[] args){
      Initialize ();

      while (true) {
        SystemEvents.CheckEvents ();
        Update ();
        Render ();
      }
    }

    public static void Initialize (){
      graphics = new GraphicsContext ();
    }

    public static void Update (){
      var gamePadData = GamePad.GetData (0);
    }

    public static void Render ()
{
      graphics.SetClearColor (0.0f, 0.0f, 0.0f, 0.0f);
      graphics.Clear ();
      graphics.SwapBuffers ();
    }
  }
}

This recipe shows us the very basic skeleton of an application. Essentially it loops forever, displaying a black screen.

private static GraphicsContext graphics;

The GraphicsContext variable represents the underlying OpenGL context. It is used to perform almost every graphically related action. Additionally, it contains the capabilities (resolution, pixel depth, and so on) of the underlying graphics device.

All C# based applications have a main function, and this one is no exception. Within Main() we call our Initialize() method, then loop forever, checking for events, updating, and finally rendering the frame. The Initialize() method simply creates a new GraphicsContext variable. The Update() method polls the first gamepad for updates (we will cover controls in more detail later).

Finally Render() uses our GraphicsContext variable to first clear the screen to black using an RGBA color value, then clears the screen and swaps the buffers, making it visible. Graphic operations in PSM SDK generally are drawn to a back buffer.

The same process is used to create PlayStation Suite library projects, which will generate a DLL file. You can use almost any C# library that doesn't rely on native code (pInvoke or Unsafe); however, they need to be recompiled into a PSM compatible DLL format.

Color in the PSM SDK is normally represented as an RGBA value. The RGBA acronym stands for red, green, blue, and alpha. Each is an int variable type, with values ranging from 0 to 255 representing the strength of each primary color. Alpha represents the level of transparency, with 0 being completely transparent and 256 being opaque.

Following the instructions presented in the Creating a simple game loop recipe, create a new solution. I have named mine as Ch1_Example2.

Phew! That sure seemed like a lot of code to simply display a single image on screen, didn't it? The truth is, you did a lot more than just load and draw a texture. Let's jump in and look at exactly what we just created.

First, we declared the following variables, in addition to our existing GraphicsContext variable:

The bulk of our activity is in the Initialize() method. Once again, we create a GraphicsContext variable, and then store the dimensions of the frame buffer in the _viewportHeight and _viewportWidth variables. Next, we create our Texture2D object, passing the constructor the filename and whether or not we want a mipmap generated.

Next, we create a _vertexBuffer object, which is going to be a fullscreen quad we can draw our texture on. We make two calls to SetVertices(). The first call is defining the x, y, and z float variables that make up the four vertices of the fullscreen quad. The second SetVertices function call is four x and y texture coordinates. Texture coordinates are represented with a value from 0 to 1.

Next, we create our _textureShaderProgram function using the default shader PSM Studio created for us. We will cover shaders in more detail later in this chapter.

Finally, we set up the _projectionMatrix, _viewMatrix, and _localMatrix objects. The projection matrix is an orthographical matrix that represents our screen. The view matrix represents the camera within the world, using Matrix4.LookAt. LookAt(), which requires 3 vectors, the first representing your eye's location in 3D space, the second, the 3D point you are looking at, and the third, the direction where "UP" is, in this case in the Y direction. Finally, the local matrix represents the position of texture, which we want to be centered in the middle of the screen.

Now, let's take a look at the Render() function, where our texture is going to be displayed to the screen. As before, we set the clear color to black and clear the buffer. Next, we generate our worldViewProjection matrix by multiplying our projection, view and local matrices together. We then bind our worldViewProjection matrix to our shader program and then set our shader program to the GraphicsContext variable. We also set our VertexBuffer object and Texture2D object to the GraphicsContext variable. The DrawArrays() call is what ties it all together, using our worldViewMatrix to transform our vertices from our VertexBuffer object and applying our texture map, rendering it all to the active buffer. Finally, we make that buffer visible, which draws it on screen.

Here is our program in action, rendering our sprite centered to the screen:

Again, if that seemed overly complex, don't panic! Most of this code only needs to be written once, and you have the option of not working at this low a level if you should choose!

Build actions will be executed when your project is compiled, copying the content to the appropriate folder, performing whatever conversions are required. If you are used to XNA, this is similar to the functionality of the content pipeline, but not programmable.

An explanation of 3D mathematics is beyond the scope of this book, but the Kahn Academy (see http://www.khanacademy.org/) is an excellent free resource with thousands of video tutorials.

This recipe builds on the code from the last recipe. Add the following using statement to the beginning of the program code:

using Sce.PlayStation.Core.Imaging

For the complete source code for this example, see Ch1_Example3.

Instead of loading a texture from an image file, we create an image dynamically. In the Image constructor, we pass the type of image we want created, the dimensions and the background color to fill it with.

Next, we draw on our newly created image using the DrawText() function, which takes as parameters the text to draw, the color to draw it in, the font to use (there is only one option, System) and the position to draw the text at. We then create a Texture2D object to hold our image. We pass its constructor the image dimensions, whether we want to generate a mipmap or not, as well as the pixel format to use. Finally, we assign the pixel data to our _texture object by calling SetPixel() function and passing in a byte array generated by calling ToBuffer() function on our image.

We had to make the change to the Render() method to support blending using the alpha channel, or background would not be properly visible through the transparent portions of the text. Run the code again without EnableMode.Blend enabled and your text will be illegible.

Now if we run our application, we will see the following screenshot:

You can also load a font by name instead of using the built in system font. If you need precise control over your text positioning or size, be sure to check out the FontMetrics and CharMetrics classes in the documentation.

You need to have installed the PlayStation Mobile SDK to have access to required files. Of course you will also require a PlayStation Mobile compatible Android device. Make sure the Android ADB driver for your phone is installed on your computer; you can download a generic version from Google's Android development website if required.

You need to make sure that USB debugging is enabled on your Android device. This varies from device to device, but is generally located in the Settings | Developer Options | USB debugging menu.

I ran into an error when trying to add my application to the key ring. To fix this, I recreated my Publisher Key. If you are working alone, this isn't a big process, but if you are part of a team, you will need to distribute the updated key.

You will need to have installed the PlayStation Mobile SDK to have the required Vita drivers installed. If you did not install the drivers as part of the install process, under a default install they are available at C:\Program Files (x86)\SCE\PSM\tools\vita\driver. Obviously you will need to have a PS Vita and a USB cable. You will need a project to run on your Vita; load either one of the examples we created earlier or one of the examples from the SDK.

Be careful while connecting the USB cable to your Vita. For some unfathomable reason, you can easily put it in upside down! If you aren't getting a connection to your device, be sure to check if your cable is in upside down mode! I thought my Vita was broken the first time I encountered this, as I left it charging, or at least I thought I did. When I came back and it was completely dead, it took a few minutes of head-scratching until I figured out what was wrong.

This recipe builds on the example created in the prior two recipes. The complete source code is available in Ch01_Example4.

In the Initialize() method, change the code as follows:

Image image = new Image(ImageMode.Rgba,new ImageSize(500,300),new ImageColor(0,0,0,0));
Image resizedImage, croppedImage;
image.DrawText("Hello World", 
   new ImageColor(255,255,255,255),
   new Font(FontAlias.System,96,FontStyle.Italic),
   new ImagePosition(0,150));
croppedImage = image.Crop (new ImageRect(0,0,250,300));
resizedImage = croppedImage.Resize(new ImageSize(500,300));
_texture = new Texture2D(resizedImage.Size.Width,resizedImage.Size.Height,false,PixelFormat.Rgba);
_texture.SetPixels(0,resizedImage.ToBuffer());
resizedImage.Export("My Images","HalfOfHelloWorld.png");
image.Dispose();
resizedImage.Dispose();
croppedImage.Dispose();

First, we dynamically generate our image just like we did in the previous recipe. We then crop that image to half its width, by calling the Crop() function and providing an ImageRect variable half the size of the image. Crop returns a new image (it is not destructive to the source image) that we store in croppedImage. We then resize that image back to the original size by calling the Resize() function on croppedImage, with the original size specified as an ImageSize object. Like Crop(), Resize() is not destructive and returns a new image that we store in resizedImage. We then copy the pixels from resizedImage into our texture using SetPixels().

Next, we call Export(), which saves our cropped and resized image in a folder called My Images as a file named HalfOfHelloWorld.png on your device. Finally, we call Dispose() on all three images, to free up the memory they consumed.

Now if you run your code, instead of "Hello World", you simply get "Hello".

When run on the simulator, export will save the image to your My Pictures folder. Be sure to call Dispose(), or wrap within a using statement all objects that implement IDisposable, or you will quickly run out of memory. Most resources like images and textures require disposal.

The complete code for this example is available in Ch1_Example5. This example adds the following two new using statements:

Create a new solution and enter the following code replacing the Main() function:

public static void Main (string[] args){
 const string DATA = "This is some data";
 
 byte[] persistentData = PersistentMemory.Read();
 
 byte[] restoredData = persistentData.Take(DATA.Length * 2).ToArray();
 string restoredString = System.Text.Encoding.Unicode.GetString(restoredData);
 
 byte[] stringAsBytes = System.Text.Encoding.Unicode.GetBytes(DATA);
 
 for(int i = 0; i < stringAsBytes.Length; i++)
  persistentData[i] = stringAsBytes[i];
 PersistentMemory.Write (persistentData);
 
 using(FileStream fs = File.Open("/Documents/Demo.txt",FileMode.OpenOrCreate)){
  if(fs.Length == 0)
   fs.Write(stringAsBytes,0,stringAsBytes.Length);
  else{
   byte[] fileContents = new byte[fs.Length];
   fs.Read(fileContents,0,(int)fs.Length);
  }
   
 }
}

The first part of this sample demonstrates using the PersistentMemory class. It is a statically available class, so you cannot allocate one. Instead you access it using PersistentMemory.Read(). This returns a byte array that you can now modify. We read some data using the LINQ extension Take() method. We multiplied the size by 2 because the string is stored as UNICODE, which requires 2 bytes per character. We then convert those bytes into a Unicode string. Next, we convert our DATA string into a byte array, then write it to persistentData byte by byte in a for loop. Finally we commit our changes to persistentMemory by calling PersistentMemory.Write(), passing in our updated persisitentMemory byte array.

The next part of the recipe demonstrates traditional file access using the standard .NET libraries, in this case File and FileStream. We open a text file in the /Documents folder named Demo.txt, creating it if it doesn't exist. If the file doesn't exist, we write our byte array stringAsBytes to the file. Otherwise, we read the file contents into a new byte array fileContents.

The first time you run this example, PersistentMemory.Read() will contain gibberish, as nothing has been written to it yet. On the second run, it will start with the bytes composing your DATA string.

Persistent storage is limited to 64 KB in space. It is meant for quickly storing information, such as configuration settings. It is physically stored on the filesystem in the /save directory in a file named pm.dat.

There are three primary locations for storing files:

The PlayStation Mobile SDK limits directory structures to at most 5 levels deep, including the filename. Therefore, /documents/1/2/3/myfile.txt is permitted, but /documents/1/2/3/4/myfile.txt is not.

The complete code for this example is available in Ch01_Example06.

Replace Main() with the following code:

public class AppMain
{
 static bool _done = false;
 public static void Main (string[] args){
  
  SystemEvents.OnRestored += HandleSystemEventsOnRestored;
  while(!_done)  {
   SystemEvents.CheckEvents();
   // Loop until application minimized then restored.
  }
 }

 static void HandleSystemEventsOnRestored (object sender, RestoredEventArgs e)
 {
  Console.WriteLine ("System restored, ok to shut down");
  _done = true;
 }
}

This code starts by wiring an OnRestored event handler to global class SystemEvents. We then loop until the _done bool is set to true. Within our loop we poll SystemEvents.CheckEvents() to see if any events have occurred. If an OnRestored event occurs, our event handler will be fired.

Our event handler HandeSystemEventsOnRestored() simply writes out a message to the console, then sets the _done bool to true, causing our loop to end, and our program to exit.

Run this example, then minimize the simulator or change applications on your device. When you refocus the application, it will fire the OnRestored event, causing your program to exit.