33
edits
Changes
Jump to navigation
Jump to search
→Basic Image Manipulation
Line 622:
Line 622:
+
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,
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,
+
+- [[user:WiiPhlex|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;
+
+<source = "cpp">LayerManager manager(3);</source>
+
+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
+
+<source lang = "cpp">
+manager.Append(&sprite);
+</source>
+
+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:
+
+<source lang = "cpp">manager.Append(&sprite);</source>
+
+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:
+
+
+<source lang = "cpp">manager.Append(&sprite2);</source>
+
+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:
+
+<source lang = "cpp">manager.Insert(&quad, 0);</source>
+
+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:
+
+<source lang = "cpp">manager.Insert(&quad, 0);</source>
+
+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:
+
+<source lang = "cpp">manager.Draw(0, 0);</source>
+
+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:
+
+<source lang = "cpp">manager.RemoveAll()</source>
+
+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():
+
+
+<source lang = "cpp">manager.GetLayerAt(1);</source>
+
+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...
- [[user:WiiPhlex|WiiPhlex]]
- [[user:WiiPhlex|WiiPhlex]]