WiiBrew

Libwiisprite/tutorial

Page Discussion
< Libwiisprite

Programming for Nintendo Wii with Libwiisprite.

Foreword

Libwiisprite

The following tutorial is by WiiPhlex

There are several things users should note before proceeding any further with the tutorial. This tutorial is released on the latest release of the Libwiisprite library, 0.3.0b which you can download here -> http://chaosteil.googlepages.com/libwiisprite-0.3.0b.tar.gz.

The tutorial will be written almost entirely in C++ with the possible exception of some C standard libraries functions. I will try and point this out where applicable. Also note that it is not a C++ programming tutorial, I will assume you have some knowledge in programming with C++ before you attempt the following. If you have learned C, and wish to use this, you will need some knowledge in Classes and protection levels, for more information on both of these topics visit www.cprogramming.com . If you are completely new to programming altogether I advise that you learn how to program C++ for PC before moving onto the Nintendo Wii. If you have programmed in C++ and are a little rusty, I have created a reference guide for some of the slightly more advanced C++ programming topics which can be viewed here http://wiibrew.org/wiki/Programming_in_C%2B%2B.

I do not guarantee the accuracy of this document, I will attempt to give all correct information, but no one is perfect, if you find an error please contact me on the one of the below ways.

I will also be referring to the Libwiisprite documentation for functions parameters and class hierarchy, and where required the source code for the functions, although if you wish to see the source code for the library you will need to contact the Author, this can be done at chaosteil@gmail.com.

If you wish to contact me, the author of this document, feel free to do so by emailing me at phlex.wii@gmail.com or sending me a pm at the wiidev forums here http://forum.wiibrew.org/. I spell words the English way, for example, initialise rather than initialize and colour instead of color. Of course if color is what a program requires I shall leave it so otherwise the program will not work as it is supposed to.

Setting up Libwiisprite for use.

If you haven’t read the foreword, read it and don’t be lazy. This will be a fairly short lesson and at this point I will assume you have downloaded the Libwiisprite. First, you need to know how to set your make file. The basic template will look something like this: 

#---------------------------------------------------------------------------------
# Clear the implicit built in rules
#---------------------------------------------------------------------------------
.SUFFIXES:
#---------------------------------------------------------------------------------
ifeq ($(strip $(DEVKITPPC)),)
$(error "Please set DEVKITPPC in your environment. export DEVKITPPC=<path to>devkitPPC")
endif

include $(DEVKITPPC)/wii_rules

#---------------------------------------------------------------------------------
# TARGET is the name of the output
# BUILD is the directory where object files & intermediate files will be placed
# SOURCES is a list of directories containing source code
# INCLUDES is a list of directories containing extra header files
#---------------------------------------------------------------------------------
TARGET		:=	$(notdir $(CURDIR))
BUILD		:=	build
SOURCES		:=	source
DATA		:=	data  
INCLUDES	:=

#---------------------------------------------------------------------------------
# options for code generation
#---------------------------------------------------------------------------------

CFLAGS	= -g -O2 -mrvl -Wall $(MACHDEP) $(INCLUDE) -I$(DEVKITPPC)/local/include
CXXFLAGS	=	$(CFLAGS)
LDFLAGS	=	-g $(MACHDEP) -mrvl -Wl,-Map,$(notdir $@).map

#---------------------------------------------------------------------------------
# any extra libraries we wish to link with the project
#---------------------------------------------------------------------------------
LIBS	:=	-lwiisprite -lpng -lz -lwiiuse -lbte -lfat -logc -lm 

#---------------------------------------------------------------------------------
# list of directories containing libraries, this must be the top level containing
# include and lib
#---------------------------------------------------------------------------------
LIBDIRS	:= 

#---------------------------------------------------------------------------------
# no real need to edit anything past this point unless you need to add additional
# rules for different file extensions
#---------------------------------------------------------------------------------
ifneq ($(BUILD),$(notdir $(CURDIR)))
#---------------------------------------------------------------------------------

export OUTPUT	:=	$(CURDIR)/$(TARGET)

export VPATH	:=	$(foreach dir,$(SOURCES),$(CURDIR)/$(dir)) \
					$(foreach dir,$(DATA),$(CURDIR)/$(dir))

export DEPSDIR	:=	$(CURDIR)/$(BUILD)

#---------------------------------------------------------------------------------
# automatically build a list of object files for our project
#---------------------------------------------------------------------------------
CFILES		:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.c)))
CPPFILES	:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.cpp)))
sFILES		:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.s)))
SFILES		:=	$(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.S)))
BINFILES	:=	$(foreach dir,$(DATA),$(notdir $(wildcard $(dir)/*.*)))

#---------------------------------------------------------------------------------
# use CXX for linking C++ projects, CC for standard C
#---------------------------------------------------------------------------------
ifeq ($(strip $(CPPFILES)),)
	export LD	:=	$(CC)
else
	export LD	:=	$(CXX)
endif

export OFILES	:=	$(addsuffix .o,$(BINFILES)) \
					$(CPPFILES:.cpp=.o) $(CFILES:.c=.o) \
					$(sFILES:.s=.o) $(SFILES:.S=.o)

#---------------------------------------------------------------------------------
# build a list of include paths
#---------------------------------------------------------------------------------
export INCLUDE	:=	$(foreach dir,$(INCLUDES), -iquote $(CURDIR)/$(dir)) \
					$(foreach dir,$(LIBDIRS),-I$(dir)/include) \
					-I$(CURDIR)/$(BUILD) \
					-I$(LIBOGC_INC)

#---------------------------------------------------------------------------------
# build a list of library paths
#---------------------------------------------------------------------------------
export LIBPATHS	:=	$(foreach dir,$(LIBDIRS),-L$(dir)/lib) \
					-L$(LIBOGC_LIB) -L$(DEVKITPPC)/local/lib

export OUTPUT	:=	$(CURDIR)/$(TARGET)
.PHONY: $(BUILD) clean

#---------------------------------------------------------------------------------
$(BUILD):
	@[ -d $@ ] || mkdir -p $@
	@make --no-print-directory -C $(BUILD) -f $(CURDIR)/Makefile

#---------------------------------------------------------------------------------
clean:
	@echo clean ...
	@rm -fr $(BUILD) $(OUTPUT).elf $(OUTPUT).dol

#---------------------------------------------------------------------------------
run:
	psoload $(TARGET).dol

#---------------------------------------------------------------------------------
reload:
	psoload -r $(TARGET).dol


#---------------------------------------------------------------------------------
else

DEPENDS	:=	$(OFILES:.o=.d)

#---------------------------------------------------------------------------------
# main targets
#---------------------------------------------------------------------------------
$(OUTPUT).dol: $(OUTPUT).elf
$(OUTPUT).elf: $(OFILES)

#---------------------------------------------------------------------------------
# This rule links in binary data with the .jpg extension
#---------------------------------------------------------------------------------
%.jpg.o	:	%.jpg
#---------------------------------------------------------------------------------
	@echo $(notdir $<)
	$(bin2o)

-include $(DEPENDS)

#---------------------------------------------------------------------------------
endif
#---------------------------------------------------------------------------------

(taken from the Libwiisprite template make file) If you wish to add other libraries to your project to this by editing the LIBS flag by appending the name of the library prefixed with a -. As this a Libwiisprite tutorial, I won’t go into much detail on make files, if you wish to learn more visit http://www.gnu.org/software/make/manual/make.html. In order to ‘install’ Libwiisprite, follow these steps

  1. Open the folder “libwiisprite/libwiisprite” then open the “include” folder. Next, copy the entire contents of the folder, there should be 8 files with the .h extension.
  2. Next, open devkitPro/libogc/include ( \ slashes for windows) and paste the includes there.
  3. Go back to libwiisprite and open the libwiisprite folder in libwiisprite. Then open lib and copy the one .a file there and paste it in devkitPro/libogc/lib/wii.
  4. Again, go back to the root of libwiisprite and open libpng, copy the contents to the same place as the other .h files and then open.
  5. Open libwiisprite/libpng/lib and copy libpng.a and paste it in devkitPro/libogc/wii.

Now you are set up to start programming.

- WiiPhlex

Setting up the Video display.

Now it is time to see some real program code! The following it taken from the Libwiisprite example template (libwiisprite\examples\template\source\template.cpp). The entire program is as follow and is the minimum to get up a screen of RGBA colour values (if you don’t understand this you will soon) and render it. The source is as follows: 

#include <wiiuse/wpad.h>
#include <wiisprite.h>

// libwiisprite uses wsp as it's namespace
using namespace wsp;

int main(int argc, char **argv)
{
	// Create the game window and initalise the VIDEO subsystem
	GameWindow gwd;
	gwd.InitVideo();
	
	gwd.SetBackground((GXColor){ 255, 255, 255, 255 });

	// Initialise Wiimote
	WPAD_Init();

	for(;;)
	{
		WPAD_ScanPads();
		if(WPAD_ButtonsDown(WPAD_CHAN_0)&WPAD_BUTTON_HOME)
			break;
		gwd.Flush();
	}
	return 0;
}

Ok, so let’s look at it piece by piece. First two lines include the required header files to just get the program going. The header file is for getting input from the wiimote which at this stage will only be used to exit the program. The functions used by this file are WPAD_Init(), WPAD_ScanPads() and WPAD_Buttons_Down(), these functions are not related to Libwiisprite so I will not describe their functions, visit the wiibrew wiki for more information on the Wiimote. The second header file, wiisprite.h, this is a fairly short file that’s main purpose is to include all the other files, yep, all this file does is add gamewindow.h, layermanager.h, layer.h, image.h, sprite.h, tiledlayer.h, and finally quad.h. Now this isn’t the best practice in programming as you should only include the files that your program will actually require, but for now don’t worry about this. Other than including the rest of the library, it defines two macros for correcting the wii pointer location to (200, 250). The next line of importance that you must note is 

using namespace wsp;

most people use std namespace a lot and may be wondering what wsp could mean, if you don’t know about namespaces I won’t tell you here as it is related to C++ programming, if you wish to learn about namespaces visit one of the many C++ programming sites. All of the Libwiisprite classes work in the wsp namespace, so this little declaration saves us typing the namespace followed by scope resolution operators followed by more tedious typing that we can’t be bothered doing. Now that we have all of our classes included into our program, we need to be able to use them. For the purpose we will just use one of these classes, GameWindow. We create an instance of the GameWindow in the main loop called gwd. The first function we call from the GameWindow class is InitVideo(), the Libwiisprite documentation defines the InitVideo function as follows 


 void wsp::GameWindow::InitVideo 	(		 ) 	
 Initializes the whole video subsystem. Should be the first command called with the library.

As you can see, this function takes care of a whole lot of dirty work that we avoid by calling a single function and not even passing it anything! Thank heavens for such a function . The next function however, is not so simple and is called as such: 

gwd.SetBackground((GXColor){ 255, 255, 255, 255 });

Again, this is part of the GameWindow class and is defined in the documentation like this: 

 void wsp::GameWindow::SetBackground 	(	GXColor 	bgcolor 	 ) 	
 Sets the background clear color 
 Parameters:
 	bgcolor 	is a GXColor containing r, g, b and a.

At this point I will explain a little about colour displays. Now I’ll assume you understand that a 800x600 display means 800 dots horizontally and 600 dots vertically, if you didn’t you do now. The tricky part about a colour display is depth. The first thing to know is that he number of bits in a colour display determines how much video card memory each pixel on the screen consumes. For example, 16 bits is 2 bytes, so each pixel of a 16 bit colour display requires 2 bytes of memory. So if your program is set to an 800x600 display resolution with 16 bit colour, your video card requires 800x600x2 bytes of memory or a total of 960,000 bytes of memory. If the same display uses 32-bit colour, the video card memory is 1,920,000 bytes or twice that required by a 16 bit scenario. For the purpose of this document, colours on the screen are red, green and blue. These are called RGB colour modes. One of the simplest display modes to understand is 24-bit colour which uses 3 bytes for each pixel. One byte represents the red intensity, on represents green and the other blue. Because a byte of memory can hold a value from 0 to 255, each of these three colour elements can be set to one of 256 intensities (the 0 is counted as being an intensity there for 1 + 255 is 256). So, a 24 bit colour may look like this (255, 0, 0), this would be full intensity red with no green and no blue, (0, 255, 0) would be no red, ‘full’ green and no blue, and of course, blue would be (0, 0, 255), every other colour falls between (0, 0, 0) which is black and (255, 255, 255) which is white. Now that you know about 24-bit displays, forget them, computers hate working in odd numbered bytes and so does Libwiisprite. All of your programs will (or at least should be) in 32 bit colour. This adds an extra byte to the colour. This extra byte is called the Alpha value and determines the opacity or transparency of a pixel. So for example let’s look at red, in a 24 bit display it would be (255, 0, 0), full red, no green and no blue. Now by default, this has an alpha value of 255, in other words it has no transparent value at all, so if we were to convert that to get the same effect in 32 bit colour, we would write it as follows, (255, 0, 0, 255). Now you can see there’s a fourth component added, that is the alpha value. If we wanted our colour to be completely transparent we would change the last value to 0. Now you’re thinking, how does all of this relate to my wee program. Now that you understand about a 32 bit colour display, take a look at the last line I showed you, in case you forgot: 

gwd.SetBackground((GXColor){ 255, 255, 255, 255 });

Now take a look at those numbers! Wo0t they make sense! This will set the background colour to full red, green, blue and alpha which will be a solid, white screen (if all goes well behind the scenes). For now, ignore the GXColor type and bask in your understanding of what a few numbers do, of course if you have done graphics programming before you will likely have known this already. Also, If you are used to programming in a more popular say Direc3D or OpenGL you will likely have had to input these as a float value between 0.0f and 1.0f. Also, you will often see 0xFF and 0x00, these are hexadecimal values, 0xFF base 16 for 255 and 0x00 is base 16 for 0. You won’t always need this function if you, say, print an entire image to your background that covers everything, but be aware, if you print an image to the screen then call this you may have unexpected consequences. After this function has done its work, control returns to the main function and WPAD_Init() is called, does its thing then goes back to the main function. Then the main function gets to the for loop. You may be wondering what for(;;) does, basically it says for no value and no expression do, in other words, its’ an infinite loop. I would do it differently but it’s easier to stick with the example. Upon entering the loop 2 more ‘wiiMote’ related functions are called, and ask if the user is pressing the home button, if so break the loop, return 0 and exit the program. If however the user isn’t pressing the home button, the program executes the Flush() function, another function found in the GameWindow class we used at the start of the program. This function is defined as follows in the documentation 

void Flush ()  Finishes rendering.

Not a huge amount of information I know, and I am not allowed to release the source for I’ll explain what it does. It copy’s the back buffer to the front buffer, waits for the vertical synchronisation then renders the image to the screen and deletes the back buffer, ready for a new image to be produced (even though it will look the same all the time in our small program here). There are a few other functions in the GameVideo class that may be of use. The first I will mention is StopVideo(), the documentation defines it like this: 

   void StopVideo ()  Shuts the video subsystem down. It won't work if Video
                      wasn't initialized before.

Again, not much info, but it doesn’t require much information to understand, this shuts down the Video systems on the Wii, it’s kind of the opposite of InitWii(), this leads me on to my second function, IsInitialized() defined in the documentation as such: 

   static bool wsp::GameWindow::IsInitialized 	(		 ) 	[static]
   Checks if the video subsystem is already initialized. 
   Returns:
   true if initialized, false if not.

You may be wondering why this function would be of any use. Once you have large programs, you may be starting and stopping your video setup with the first function I mentioned and InitVideo(), so you may also want to check if you have your Wii initialised and if it isn’t then call the InitVideo() function, such code may look like this: 

If ( ! IsInitialzed())
   {
     InitVideo()
   }

There’s another two functions that you may want to use, and they are GetWidth() and GetHeight. They get the width and height of the current screen. A possible application of this is to make sure your character doesn’t go beyond the edge of the screen, or where to draw your background or where to print your menu so that its centred. That’s it for this lesson, I would advise you play around with the numbers in the SetBackground() function if you still don’t see how they work, playing with numbers can teach you an awful lot. Also, try and replace the wiisprite.h with the only header(s) that are required for this program.


- WiiPhlex

Loading and printing images.

This lesson will deal largely with the Image class and Layer class, simply include Image.h and Layer.h in your programs. The first thing we need to know is that there are two LoadImage() functions the first: 

   IMG_LOAD_ERROR LoadImage (const char *path, IMG_LOAD_TYPE loadtype=IMG_LOAD_TYPE_PATH)

and 

   IMG_LOAD_ERROR LoadImage (const unsigned char *path, IMG_LOAD_TYPE loadtype=IMG_LOAD_TYPE_BUFFER)

Here’s a quote from the author of Libwiisprite: “There are some situations however, where you want to load from a buffer. Say, you have a very small application you just want to run very fast. Or maybe you have your own package system where you can extract each file with its own buffer. Anyway, you will need a way to load an image directly, and not through the filesystem.” I will go over both methods of loading an image. So let’s look more closely at the first function. 


  IMG_LOAD_ERROR wsp::Image::LoadImage 	(	const char * 	path, 
  		IMG_LOAD_TYPE 
  loadtype = IMG_LOAD_TYPE_PATH
  	)

Loads an image from a file. Width and height have to be a multiple of 4, or it won't load. Once an Image is initialized, it can't be initialized again. Uses fopen(), so some basic filesystem initialization is required. 

  Parameters:
  	path 	The path to the file. 
  	loadtype 	Set this to how you want to load this image. (This is probably a path) 
  Returns:
  An error code based on loading status.

Before you can load your image, you need to create an instance of the a class that will allow you to use your image or sprite in the way you wish, for example, for a static background (I refer to static to mean a still image not a member that exists for an entire class) you may consider using the Image class, but if you wanted to create a sprite you would use the Sprite class. I will be using snippets from Libwiisprite/examples/spritetest and explaining the code from that, I cannot add all of the code as one file contains raw data for an image which is 545 lines long. If you want to see this file it is Libwiisprite/examples/spritetest/source/libwiisprite.cpp. Open the source file at Libwiisprite/examples/spritetest/source/spritetest.cpp. The first line of interest to us is this 

Sprite sprite; // The drawable object we can modify.

This creates a sprite object of type Sprite, this is probably the most flexable class for manipulating an image, although you should use it in conjunction with the Image class, this will be shown in the following example. But remember that if you don’t should select your classes dependant on what you actually need, not just you can select a certain type. Continuing on now, we see another four declarations of various class types, the only ones we are concerned with are 

Sprite sprite2; // Another drawable object we can modify.
Image image; // Holds our image/texture from the SD Card.
Image image2; // Holds our buffer image/texture.

At this point don’t worry why there are declarations of the same things twice in small example, basically, it’s to show you how to load an object of type Sprite from the buffer as well as from file and the same goes for the two images of type Image. Skip a few lines and go to 

	// Initialize filesystem to load from SD Card
	fatInitDefault();

This function is included in fat.h and is called as #include <fat.h>, this is for file management and makes it easier and safer to handle files from the SD card, unless you know what you are doing with file handling and even if you do, it’s always a good idea to include this. Now we shall move down a little further and skip a few things along the way until we reach this wee section of code here: 

if(image.LoadImage("libwiisprite.png") != IMG_LOAD_ERROR_NONE)exit(0);

This function is one of the ones that reads from the SD card. If the image isn’t at found at the location specified in the quotation marks, the function will return false and the program will automatically exit, otherwise it will return an address in memory where the image has been loaded and assign a value to our Image object, image. The next line is very similar but differs substantially in the details: 

if(image2.LoadImage(libwiisprite) != IMG_LOAD_ERROR_NONE)exit(0);

libwiisprite (the one between the bracts in the above line) is defined in libwiisprite as a huge, fat array of constant, unsigned char’s. It’s been generated so that it can be loaded directly into memory on runtime which is what happens as soon as the program sees this chunky piece of code. So the above code segment attempts to find it in memory, if the image isn’t in memory, the program will exit, otherwise the value of libwiisprite is assigned to image2, and has been loaded from the buffer rather than the SD card. Easy! Next we make use of our two sprite objects, sprite and sprite2 (imaginative names aren’t they?), with these two lines: 


sprite.SetImage(&image);
sprite2.SetImage(&image2);

To properly understand what’s going on we are going to have a look at how the documentation defines the SetImage() function, just have to love the documentation don’t you! 


  void wsp::Sprite::SetImage 	(	Image * 
  image, 
  		u32 	frameWidth = 0, 
  		u32 	frameHeight = 0	 
  	)

Assigns this sprite to an image. If there is already an image with the same size, no data gets changed. 

  Parameters:
  	image 	The image for this sprite. 
  	frameWidth 	The width of the frame. Should be a multiple of image->GetWidth()
               or 0 if it should get the same width as the image. 
  	frameHeight The height of the frame. Should be a multiple of image->GetHeight()

or 0 if it should get the same height as the image.


At this stage, we are only using the first parameter and ignoring the second two. After consulting the source code for this function, it will work fine with no parameters, it will set them to 0 if no other is there. What we have done with our two images is pass the address of the images using the address of operator (&), then the function will handle the image for us the rest of the way. Now we have an image loaded into our sprite with all the abilities of the Image class as well as the Sprite class. Next line of interest is this one 


sprite.SetPosition(0, 0);

Again we shall now look at the documents definition of the SetPosition() function in case you can’t guess what those 2 parameters represent. 

  void wsp::Layer::SetPosition 	(	f32 	x, 
  		f32 	y	 
  	)			
  Changes the absolute position of the layer on the viewport. 
  Parameters:
  	x 	The new X position. 
  	y 	The new Y position.


Simple enough, takes as parameters 2 values, x then y coordinates. This is the simplest way of going about this. At this stage you should know about screen coordinates. This system uses 2D coordinates with x running horizontally and y running vertically. Here’s an example from the documentation of what the system looks like.


Coordinates: 

.------------> X (640, horizontal)
|
|
|    Coordinate system starts at (0;0).
|
|
V Y (480, vertical)

It’s just a 2D coordinate system with an inverted vertical (or y) axis. With the origin (0,0) at the top right hand corner, x increases moving right of the screen and y increases moving down. A note on depth and z is that in computers it usually increases going into the screen and decreases coming out. The reason that the coordinate system works this way is because of the way that the back buffer prints to the front buffer (front buffer is a fancy name for screen), it starts printing from the top left corner at (0,0) then moves one pixel across the x axis to (1,0). Once a top line has been rendered to the front buffer, it will start printing at the next line and do it all over again until the entire image is drawn. This happens so fast that you can’t actually see each pixel being drawn. So when we use this call: 

sprite.SetPosition(0, 0);

We are setting its location to print the top left corner of the image to top left corner of the screen. This is commonly used when printing backgrounds to cover the entire screen regardless of screen size/resolution. The next print call we encounter is as follows: 

sprite2.SetPosition(320, 240);

That’s it for this lesson now that you know how to load an image from the buffer or from the SD card and print them to the screen. One thing to note is that your images resolution must be a multiple of four otherwise your program will not be happy with you, in the next we will look at some more interesting stuff, specifically, manipulating images using Libwiisprite for more interesting effects.

- WiiPhlex

Basic Image Manipulation

I will still use spritetest.cpp for the purpose of this lesson. Now that we have a couple of images loaded and on screen, we want to be able to play around with them. There are several functions in Libwiisprite that allow you to manipulate images in various ways. Specifically, we will look at transformations to our images through SetStretchHeight(), SetStretchWidth, SetZoom and SetTransparency as well as a few other ‘Get’ functions. We will start this lesson at line 99 and 100 of spritetest.cpp 

if(pressed & WPAD_BUTTON_MINUS)
sprite.SetZoom(sprite.GetZoom()-0.1f);

Ignore the first line for now, the second contains 2 very easy to use functions for getting and setting zoom values. Before I continue have a quick look at the definition for each of these functions: 

  void wsp::Sprite::SetZoom 	(	f32 	zoom 	 ) 	
  Sets the zooming of the sprite. It resets any defined stretch values. 
  Parameters:
   	zoom 	The new zoom of the sprite. 1 is normal size, cannot be smaller
               than 0.

CURRENT ZOOM CANNOT BE SMALLER THAN 0! Make sure you go by this rule, to make sure that your images zoom level never goes below 0 you may add a simple check like this: 

if(pressed & WPAD_BUTTON_MINUS && sprite.GetZoom() >= 0)
sprite.SetZoom(sprite.GetZoom()-0.1f);

This simply checks sprites zoom using the GetZoom() function defined like this: 

  f32 wsp::Sprite::GetZoom 	(		 ) 	const
  Gets the zooming of the sprite. If StretchWidth is not the same as
  StretchHeight, it returns 0. 
  Returns: The current zoom of the sprite. 1 is normal size.

This will return a float value which is being applied to the current image to scale using some formula we don’t need to worry about (thanks Libwiisprite!). So the expression 

if(pressed & WPAD_BUTTON_MINUS && sprite.GetZoom() > 0)

Will be true if the user is pressing the minus button and the Zoom factor for sprite is greater than 0. Note, don’t set the sprite.GetZoom() expression to >= 0, otherwise, if = sprites zoom factor == 0 then it will decrease it further, not something we want to do as this would put it in the negatives, who knows what horrible consequences this may have! So now we understand GetZoom, what about SetZoom? Well, again this is another very easy function to use, one parameter of type float. In our example it’s called like this: 

sprite.SetZoom(sprite.GetZoom()-0.1f);

if the player is pressing the minus button then this line of code executes, it will use GetZoom() to return the current zoom factor, then decreases it by a value of 0.1. So say for example that the current zoom factor is 1, the native resolution of the image, then in plain English, the expression would look like this: “set sprites zoom factor to 1 – 0.1 which equals 0.9, then multiply the images native resolution by this”. That’s simple enough in my opinion, that you should now be able to understand the next two lines in the program: 

if(pressed & WPAD_BUTTON_PLUS)
sprite.SetZoom(sprite.GetZoom()+0.1f);

Just in case you aren’t sure what this does, it checks to see if the user is pressing the plus button and if this evaluates to true, then sprites zoom factor is increased by 0.1. You may be wondering why there’s and f after the increase value, this is just how most programs accept a float value, if you’ve done much graphics programming you will used to setting verticies, materials, colours, alpha values and all manner of things as a value with f at the end. Now we will move onto the next few lines of interest; 

if(pressed & WPAD_BUTTON_A && sprite.GetTransparency() < 0xff-4)
sprite.SetTransparency(sprite.GetTransparency()+5);

if(pressed & WPAD_BUTTON_B && sprite.GetTransparency() > 4){
sprite.SetTransparency(sprite.GetTransparency()-5);

In many ways this is similar to the lines we just looked at, except that it changes the value of the images transparency, I will refer to transparency as alpha from now on as its the more ‘correct’ term and far easier to type. Now for a short lesson in alpha. Alpha determines the overall opacity of the pixel, usually a value from 0 to 255 (just like the RGB, it use a byte of memory to hold it) or in many API’s, a float value from 0.0f to 1.0f, we will use the first mode for this example. If the alpha is set to full (255) then the surface is fully opaque, or ‘solid’, whereas, if the alpha value is set to 0 the surface is completely transparent, clear, invisible, any number of words could describe this. When you load an image, usually it will have an alpha value of 255 unless specified differently in the image data itself. Now we will have a look at the SetTransparency() function: 


   void wsp::Sprite::SetTransparency 	(	u8 	alpha 	 ) 	
   
   Sets the transparency of the sprite. 
   Parameters: alpha 	Sets the transparency. Has a range from 0x00 (invisible)
                       to 0xFF (fully visible)

The values 0x00 and 0xFF are hexadecimal or more commonly called ‘hex’, this is how most of your image will be handled although the functions are just as happy to work with decimal as shown in the code segment at the start of the Transparency section. In our example, 0x00 is the same as 0 (no alpha, and 0xFF is 255 (fully opaque). Now let’s look again at that code segment 

if(pressed & WPAD_BUTTON_A && sprite.GetTransparency() < 0xff-4)
sprite.SetTransparency(sprite.GetTransparency()+5);

if(pressed & WPAD_BUTTON_B && sprite.GetTransparency() > 4){
sprite.SetTransparency(sprite.GetTransparency()-5);

Line one will see if the user is pressing A first of all. The next part is a little trickier to understand, lets look at it in small sections at a time to see exactly what is happening. 

sprite.GetTransparency() < 0xff-4

GetTransparency() is the alpha equivalent to GetZoom(), it is defined as such: 

   u8 wsp::Sprite::GetTransparency 	(		 ) 	const
   Gets the transparency of the sprite. 
   
   Returns:
   The current transparency of the sprite. Has a range from 0x00 (invisible) to
   0xFF (fully visible)

So now we know what GetTransparency() does (if you didn’t know before), then it will compare that value to 0xFF – 4 (think of it as being 255 – 4 = 251). To put this into an equation, we will assume that the native alpha value of the image is 255, or 0xFF:

If the player is pressing A AND 255 is less than 251, execute the next statement.

Say the user was pressing A, that will result the first part of the expression to true, however, the alpha of the image must also be less than 251 in order to do this, as shown in the above example, it is fairly obvious that 255 is not less than 251, therefore the expression will return false and you aren’t able to increase the alpha anymore, after all how can you make something more solid than solid? Now we are going to look another example where the images alpha is less than 0xFF – 4, let’s say the alpha value of the image is equal to 100, and A is being pressed, because 100 is less than 251 and A is being pressed the if statement is true, so the program executes this line of code: 

sprite.SetTransparency(sprite.GetTransparency()+5);

This will call SetTransparency() and pass it the current alpha and increase it by a value of 5. The next two lines of code are more or less the same but the user must be pressing B and the images alpha must be greater than 4, if so then it will call SetTransparency() to decrease the current alpha by a value of 5. The reason that the alpha must be greater than (but not and equal to) is so that if the alpha vale is equal to 5 and it calls the SetTransparency() function then the current alpha value will be 0, if it were 0 and you were able to decreases the alpha value further you would have negative values (obviously) which won’t go down well with the program at all! Always make sure you have checks to stop values going below thresholds, the program will almost never do this for you so you must code your applications, games etc carefully to avoid these things. That’s four functions down, let’s move onto the next two Get and Set functions. 


if(pressed & WPAD_BUTTON_UP)
sprite2.SetStretchHeight(sprite2.GetStretchHeight()+0.1f);
if(pressed & WPAD_BUTTON_DOWN)
sprite2.SetStretchHeight(sprite2.GetStretchHeight()-0.1f);

This works in the same way as the other Get and Set functions, but these adjust the Height of the images. First the program asks if the player is pressing up, if he/she is, then sprite2’s images height will be increased by a scale factor of its current Height + 0.1, again a float value, Here are the two Get and Set functions for height: 

   void wsp::Sprite::SetStretchHeight 	(	f32 	stretchHeight 	 ) 	
   Sets the height stretch of the sprite. 
   Parameters:
   	stretchHeight 	Stretches the height of the sprite by this value. 1 is
                       normal size, cannot be smaller than 0.
   
   
   f32 wsp::Sprite::GetStretchHeight 	(		 ) 	const
   Gets the height stretch of the sprite. Is equal to zoom vallue if zoom was set. 
   Returns:
   The current height stretch of the sprite. 1 is normal size.

Again don’t let the stretch factor go below 0, a check similar to the one I showed with zoom will fix the problem here. GetStretchHeight() will return the current height stretch factor, when an image is loaded this value is 1 and all other values are based on that. The second two lines do pretty much the same thing again except it requires input of down from the wiimote and decreases the stretch height. Next two functions... 

if(pressed & WPAD_BUTTON_RIGHT)
sprite2.SetStretchWidth(sprite2.GetStretchWidth()+0.1f);
if(pressed & WPAD_BUTTON_LEFT)
sprite2.SetStretchWidth(sprite2.GetStretchWidth()-0.1f);

same as its preceding functions although this changes the Width instead, hence the function GetStretchWidth() and SetStretchWidth(). Now we have those functions out of the way we shall move down the loop to a new line: 

 sprite.Move(-((f32)sprite.GetWidth()/2), -((f32)sprite.GetHeight()/2));

The Move() function is defined as follows in the documentation: 

   void wsp::Layer::Move 	(	f32 	deltaX, 
   		f32 	deltaY	 
   	)	

   Moves the layer some units. 
   Parameters:
   	deltaX 	Moves the layer a specific amount of units to the left/right. 
   	deltaY 	Moves the layer a specific amount of units up/down.

This function is found in the Layer class, so if you wish to use this function be sure to include Layer.h in your program. First thing first, delta, if you don’t know what this is it simply means ‘the change in’, it’s often used in physics calculations and its mathematical symbol is Δ. So ΔY means the change in Y and ΔX is the change in the value of X. These X and Y values are Cartesian coordinates. The function takes two parameters, a value of type f32 that is for the x and another for y. So the line 

sprite.Move(-((f32)sprite.GetWidth()/2), -((f32)sprite.GetHeight()/2));

calculates -((f32)sprite.GetWidth()/2), in other words, the inverse of the width of sprite divided by 2, and the second line does the same thing but uses GetHeight() instead of GetWidth(). This is a particularly useful function if you want to, well, move your images around, look at your average 2D side scroller, everything moves in some or other way, the character, the enemy’s, and of course the background. Say you wanted to make your image move right when you press the right button and move it left when you pressed the left button, your code might look something like this: 

if(pressed & WPAD_BUTTON_RIGHT)
sprite.Move( 1, 0 );

if (pressed & WPAD_BUTTON_LEFT)
sprite.Move(-1, 0 );

In the first pair of lines, a check is done to see if the player is pressing the right button, if this results to be true, then sprite.Move() is called. I assign the first parameter which is the x value to change, 1, and the second parameter which is the y value, to 0. I set the second to 0 so that the image stays at the same height, after all we only want it to move along the x axis. You can do the same for the y axis by putting in something like this: 

if(pressed & WPAD_BUTTON_UP)
sprite.Move( 0, -1 );

if (pressed & WPAD_BUTTON_DOWN)
sprite.Move(0, 1 );

This moves the image up the screen if you press up and down if you press down, remember that the y axis increases as you move down, therefore to move up you must decreases the current y value of the image. The last function that we will look at in detail is the SetRotate() function: 


   void wsp::Sprite::SetRotation 	(	f32 	rotation 	 ) 	
   Sets the rotation angle of the sprite. 
   Parameters:
   	rotation 	The new angle of the sprite. It is measured in degrees/2,
                   so if 90 degrees is wanted, 45 degrees should be the passed

parameter.

In the program the following line of code is called. 

sprite.SetRotation(ir.angle/2);

Ignore ir.angle , it’s to do with the an abbreviation for infa red and is in the ir_t structure. SetRotate() is another easy function to use, just pass the number of degrees you want and divide by two or if you know how much you want to do, calculate the value then pass it before a build. For example, if we wanted to turn it 90 degrees (as shown in the parameter documentation) we could either do it like this: 

sprite.SetRotation(90/2);

or if we only needed to do it once and not get the degrees on the run we could do the calculation before hand to get the result passed to the function to save out program using up a couple of cycles to do it, like this: 

sprite.SetRotation(45);

A more flexable method again is to have a variable called degrees (or whatever you want to call it), and the value of degrees depends on some input, say the angle of the wiimote then call the function like this: 

Sprite.SetRotate(degrees/2);

You can also get the current rotation by calling the GetRotation() function which is defined as follows: 

   f32 wsp::Sprite::GetRotation 	(		 ) 	const
   Gets the rotation angle of the sprite. 
   Returns: The current angle of the sprite.

Returns a value of type f32 by default this is 0 when the image is loaded unless specified otherwise. Now we are almost at the end of the program, the last two functions that are called are these: 

manager.Draw(0, 0); 
gwd.Flush();

These two functions require the inclusion LayerManager.h and GameWindow.h as well as an instance of the classes. The first of these two functions, Draw() is used to determine off set and the second one does the rest of the rendering work but don’t worry about these too much I’ll explain them later, so that’s it for this lesson, a long lesson with lots of handy functions that are easy to use. Till next time,

- WiiPhlex

Layer Management.

Layers are a key element to using the Libwiisprite effectively and efficiently. They decide what you see, where you see it and everything in between. I’ll still by using the trusty file, spritetest.cpp by taking examples from it and how they work. First thing we need to use layers is to include LayerManager.h, this is done in our program by including libwiisprite.h, which if you remember includes everything else in the library. Now look further down the source at line 42; 

LayerManager manager(3);

This is the first call in the program to LayerManager, this creates an instance of LayerManager called manager and calls its constructer and passes 3 to it. This means that we now have a limit of 3 layers for this layer manager. What the constructer does is create an array of (in this case) 3 elements of type Layer. So it will look something like this (note its only and abstraction to make it easier to understand what it looks like in memory): 

    elements
     0    1     2
  [null][null][null]

This is not a dynamic array, it is fixed on run time to the value you pass to the constructor so make sure you change the number to whatever is relevant to your program. The documentation defines it as; 

  wsp::LayerManager::LayerManager 	(	u32 	boundary 	 ) 	
  Constructor. 
  Parameters:
  	boundary 	Specifies how many layers can be grouped into this manager.

Ok, so now we have a layer manager set up, how do we use it? Let’s take a look at the source code 

manager.Append(&sprite);

The append function is in the LayerManager class and is defined as such: 

  void wsp::LayerManager::Append 	(	Layer *  
  layer 	 ) 	
  Appends a layer at the end, thus drawing it at last. 
  Parameters:
   	layer 	The layer to append. If it is already in the list, it gets removed first.

This function takes one parameter and that’s the address of a layer object. Some things to note about our manager object, it is essentially an array, thinking about it in this manner will help you understand layers much easier. Now with this in mind let’s look at that line again: 

manager.Append(&sprite);

Append as you should know means ‘add at the end’, and when you think in terms of an array, it would add at the lastlocation + 1. Currently our manager has no elements, so passing the address of sprite to Append() will add it to the element 0 as arrays begin a 0 not 1. So now our manager will look like this: 

    elements
     0      1     2
  [sprite][null][null]

The next line: 


manager.Append(&sprite2);

Appends another object to the manager, this time its sprite2, now to update our manager it will look like this 

    elements
     0       1       2
  [sprite][sprite2][null]

Now 2 of our elements ( 0 and 1 ) have objects in them, simple enough so far, now I introduce to you the Insert() function found in the LayerManager class: 

  void wsp::LayerManager::Insert 	(	Layer * 
  layer, 
  		u32 	index	 
  	)	
  		
  Inserts a layer into the manager. 
  Parameters:
  	layer 	The layer to insert. If it is already in the list, it gets removed first. 
  	index 	The new index of the layer. Can't be bigger than GetSize().

Very similar to the Append() function, but this lets you add objects to your manager where ever you want. And that’s what we do with the next line: 

manager.Insert(&quad, 0);

Just like with the Append function, it requires the address of an object to add to the list, but as well as this it requires the element, where you want to insert. In the above it adds at the element 0, which is the first. Inserting here will increment the element number of each element that is greater than that of the inserted layer, if your list is full and you add something at the start, the last layer will be deleted. Here’s a visual representation of Inserting a layer to a full list: 

           elements
      0        1        2               List is full
  [object1][object2][object3]

Calling: manager.Insert(object4, 0); 

            elements
       0       1        2                           
  [object4][object1][object2]   -> object3 is lost in memory. NOT GOOD!!

To avoid losing objects in memory add a check to make sure that there is an empty, or null, element in the node, if there isn’t and you still wish to add an object delete one of the elements and Insert the object where required. Back to our program now, after calling this line: 

manager.Insert(&quad, 0);

our manager will look like this: 

         elements
     0      1       2
  [quad][sprite][sprite2]

Pretty slick isn’t it? Simple as that! Now you’re saying why on earth did I do all of that? Well simply put, this will now dictate what is drawn when. You may recall at the end of the previous lesson I gave you a very quick bit of information about this line: 

manager.Draw(0, 0);

well now we are going to understand exactly what this function does. For your reference it is found at lines 130 and 137 in spritetest.cpp, the function is defined: 

   void wsp::LayerManager::Draw 	(	s32 	x, 
   		s32 	y	 
   	)			const
   Draws all the layers in this LayerManager. 
   Parameters:
   	x 	The X offset for drawing. 
   	y 	The Y offset for drawing.

For the most part, you will simply leave the parameters as 0, 0 for simplicity’s sake, although it’s important to understand exactly what they are. The first parameter determines how far along the x axis the back buffer should start drawing to the front and the second relates to where the frame starts being printed on the y axis, this may be a negative value. Now you may be wondering why you would do this, an example, (just an example mind) is in say a side scroller, while there are lots of bombs dropping on the map, the screen shakes wildly around to give a better cinematic effect from the bombs exploding than just the usual still screen. At this point you would generate an image on the back buffer slightly larger than the screen and plug a formula into both of those parameters that would change the offset to make it look like a shuddering screen. another example is simply moving a menu from one side to the other like, say the iPhone, and you could fade it while it goes, then the next screen could slide in and fade in. These are just random babblings by me, feel free to use this function how you want, but most of the time you will call it as 0, 0. Now to apply what you have learned about the LayerManaer class to this function. What happens when you call this function, is that the array acts sort of like a z buffer, the object at element 0 will be printed first, and in the case of our list, this is quad, this servers as a background, so it would make sense to print it at the back, next, element 1 is printed. This is out sprite object. Because of the way that this draws on the back buffer, every pixel that sprite is on will completely overwrite the ones that were behind it, in this case, where ever sprite is. But that’s supposed to happen so don’t worry, it will update every frame so your quad/background or whatever will remain intact waiting to be rendered next time. The Draw() function iterates through your manager until it has printed all of the images onto the buffer and created its nice image. That finishes all the calls for Manager in this application so then Flush() finishes the rendering and prints everything to the screen for you to admire. I would still like to explain the other functions in the LayerManager class that weren’t used in spritetest. The first of these functions is Remove(). 

  void wsp::LayerManager::Remove 	(	Layer * 
  layer 	 ) 	
  Removes a layer from the list. 
  Parameters:
  	layer 	A layer that is in the list.

Say we have out manager set up like this: 

           elements
      0        1        2                           
  [object1][object2][object3]

Then we call Remove() like this: manager.Remove(&object1); Now our list will look like this: 

         elements
     0      1        2                           
  [null][object2][object3]

You may insert an object at element 0 as the function checks if the element is null or not. Simple enough to understand, the function requires the address of the object to remove. Next function on my list is RemoveAll(): 


  void wsp::LayerManager::RemoveAll 	
  (		 
  ) 	
  Clears the whole LayerManager from all Layers.

Deletes everything in the current list, example of a call would look like this: 

manager.RemoveAll()

Requires no parameters.

On we go! Next function is GetSize: 

  u32 wsp::LayerManager::GetSize 	(		 ) 	const
  Returns the size of the list of layers. 
  Returns: The size of the current layerlist.

A useful check to perform when Inserting and appending layers is to check where you are inserting against object.GetSize, this will make sure you don’t go and accidently lose things in memory and get memory access violation errors cropping up with possible system crashes! Next function is GetLayerAt(). I won’t post the documentations definition as I will only briefly cover how to use it. Example of how it works: Say we have our list set up like this: 


              elements
        0        1        2                           
    [object1][object2][object3]
     000000    000001  000002  - example memory addresses


Now a call to GetLayerAt(): 


manager.GetLayerAt(1);

What this does is return the address at the specified element, in this case, we have passed 1 to the function. Then the function declares a variable and assigns the value passed to it. It then iterates through the layer until the value passed == the element your at and returns the address. So in the case of out example here, it would return 000001. If we passed 2 to GetLayerAt() then we would get 000002 (note these addresses are somewhat made up by me, completely). There’s only one other function in the LayerManager class and that is SetViewWindow(), I won’t go over this yet though as it can be rather daunting (by Libwiistandards). Until then...

- WiiPhlex

Retrieved from "https://wiibrew.org/w/index.php?title=Libwiisprite/tutorial&oldid=24436"