The basic building block for making things with Pixi is an object called a sprite . Sprites are just images that you can control with code. You can control their position, size, and a host of other properties that are useful for making interactive and animated graphics. Learning to make and control sprites is really the most important thing about learning to use Pixi. If you know how to make and display sprites, youre just a small step away from starting to make games or any other kind of interactive application.
But before we can start making sprites, we have to create some sort of rectangular screen to display them on. Lets find out how to create one.
Creating the Renderer and Stage
Pixi has a renderer object that creates a display screen for you. It automatically generates an HTMLelement and figures out how to display your images on the canvas. But you also have to create a special Pixi Container object called the stage . (Dont worry, youll find out a little later in this chapter exactly what Container objects are and why you need them.) This stage object is going to be used as the root container that holds all the things you want Pixi to display. Heres the code you need to write to create a renderer and stage . Add this code to your HTML document between the tags:
//Create the renderer
let renderer = PIXI.autoDetectRenderer(256, 256);
//Add the canvas to the HTML document
document.body.appendChild(renderer.view);
//Create a container object called the `stage`
let stage = new PIXI.Container();
//Tell the `renderer` to `render` the `stage`
renderer.render(stage);
This is the most basic code you need write to get started using Pixi. It produces a black 265 pixel by 256 pixel canvas element and adds it to your HTML document. Figure shows what it looks like in a browser when you run this code.
Figure 1-1.
Pixis renderer displays a black square in the browser
This simple black square should fill your little programmers heart with pure joy! Thats because its the first and most important step to begin displaying things with Pixi. Lets take a closer look at what all this code is doing.
Render Options
Pixis autoDetectRenderer method figures out whether to use the Canvas Drawing API or WebGL to render graphics, depending on which is available.
let renderer = PIXI.autoDetectRenderer(256, 256);
Its first and second arguments are the width and height of the canvas. However, you can include an optional third argument with some additional values you can set. This third argument is an object literal, and heres how you could use it to set the renderers anti-aliasing, transparency, and resolution:
renderer = PIXI.autoDetectRenderer(
256, 256,
{antialiasing: false, transparent: false, resolution: 1}
);
This third argument (the object highlighted in the preceding) is optional. If youre happy with Pixis default settings, you can leave it out; theres usually no need to change them. But what do those options do? The antialiasing option smooths the edges of fonts and graphic primitives. (WebGL anti-aliasing isnt available on all platforms, so youll have to test this on your applications target platform.) The transparent option makes the canvas background transparent. The resolution option makes it easier to work with displays of varying resolutions and pixel densities. Usually, just keep resolution at 1 for most projects, and youll be fine. But take a look at for more information about working with different resolutions.
Note
The renderer has an additional, fourth, option called preserveDrawingBuffer that defaults to false . The only reason to set it to true is if you ever have to call Pixis specialized dataToURL method in a WebGL canvas context. You might have to do this if you ever want to convert a Pixi canvas to an HTML image object.
Pixis autoDetectRenderer will decide whether to use the Canvas Drawing API or WebGL to display images. It defaults to WebGL, which is good, because WebGL is incredibly fast and lets you use some spectacular visual effects that youll learn all about in this book. But if you have to force Canvas Drawing API rendering over WebGL, you can do it like this:
renderer = new PIXI.CanvasRenderer(256, 256);
Only the first two arguments are required: width and height.
You can also force WebGL rendering like this:
renderer = new PIXI.WebGLRenderer(256, 256);
Now lets find out how to improve the appearance of the renderer.
Customizing the Canvas
The renderer.view object is just a plain old ordinaryobject, so you can control it the same way you would control any other canvas object. Heres how to give the canvas an optional dashed border:
renderer.view.style.border = "1px dashed black";
If you have to change the background color of the canvas after youve created it, set the renderer objects backgroundColor property to any hexadecimal color value. Heres how you could set it to pure white:
renderer.backgroundColor = 0xFFFFFF;
Note
A web search will turn up many hexadecimal color charts that you can use to select an appropriate background color.
If you want to find the width or the height of the renderer, use renderer.view.width and renderer.view.height .
To change the size of the canvas, use the renderers resize method, and supply any new width and height values, as follows:
renderer.resize(512, 512);
If you want to make the canvas fill the entire window, you can apply this CSS styling:
renderer.view.style.position = "absolute";
renderer.view.style.width = window.innerWidth + "px";
renderer.view.style.height = window.innerHeight + "px";
renderer.view.style.display = "block";
But, if you do that, make sure you also set the default padding and margins to 0 on all your HTML elements with this bit of CSS code:
* {padding: 0; margin: 0}
(The asterisk, *, in the preceding code, is the CSS universal selector, which just means all the tags.) Without this bit of CSS, you might notice a few pixels of default padding between the edge of the browser and Pixis canvas.
Scaling the Canvas to the Browser Window
You can use a custom function called scaleToWindow() to scale Pixis canvas to the maximum size of the browsers window. (Youll find scaleToWindow in the library folder of this books source code, or scaleToWindow s own source code repository: github.com/kittykatattack/scaleToWindow .) scaleToWindow will also align the canvas for the best vertical or horizontal fit inside the browser window. For example, if you have a canvas thats wider than it is tall, it will be centered vertically inside the browser. If the canvas is taller than it is wide, it will be centered horizontally. Figure show an example of these two alignments.