Merge pull request #50 from ricardoquesada/general_fixes

fixes

Author: ricardoquesada

13.md

@@ -1,18 +1,24 @@
 # Chapter 13: Audio
 
-Your game will surely need sound! Cocos2d-x provides an audio engine so wasy we 
-call it `SimpleAudioEngine`. `SimpleAudioEngine` can be used to play background 
-music as well as sound effects through out your game play. `SimpleAudioEngine` is 
-a shared singleton object so you can simple call it fromanywhere in your code. When 
-creating a sample `HelloWorld` project we do all the setup required for you, out of 
-the box. `SimpleAudioEgnine` support a number of formats, including *MP3* and 
+Your game will surely need sound! Cocos2d-x provides an audio engine so ways we
+call it `SimpleAudioEngine`. `SimpleAudioEngine` can be used to play background
+music as well as sound effects through out your game play. `SimpleAudioEngine` is
+a shared singleton object so you can simple call it from anywhere in your code. When
+creating a sample `HelloWorld` project we do all the setup required for you, out of
+the box. `SimpleAudioEgnine` support a number of formats, including *MP3* and
 *Core Audio Format*
 
 ## Getting Started
-There are considerations to keep in mind when using audio in your game. Mostly 
-when operating on mobile devices such as phones and tablets. What happens when 
-you multi-task on your phone and are switching bewteen apps? Or when a phone 
-call comes in? You need to handle these exceptions in your game. Fortunately we 
+
+FIXME: this is not "getting started". Before this I just say: This is how to play a sound,
+this is how to play a music, and stop
+
+FIXME: And an "advanced" section I will mention the setup, multi-tasking etc.
+
+There are considerations to keep in mind when using audio in your game. Mostly
+when operating on mobile devices such as phones and tablets. What happens when
+you multi-task on your phone and are switching between apps? Or when a phone
+call comes in? You need to handle these exceptions in your game. Fortunately we
 help you here.
 
 In `AppDelegate.cpp`, notice the following methods:
@@ -35,32 +41,37 @@ void AppDelegate::applicationWillEnterForeground() {
 }
 ```
 
-Notice the commented out lines for `SimpleAudioEngine` make sure to 
-uncomment these if you are using `SimpleAudioEngine` for background sounds 
+Notice the commented out lines for `SimpleAudioEngine` make sure to
+uncomment these if you are using `SimpleAudioEngine` for background sounds
 and sound effects.
 
 ## A simple to use API
 The API for `SimpleAudioEngine` is, of course, simple!
 
 ### Play background music
-Play an audio file for use as background music. This can be repeated 
+Play an audio file for use as background music. This can be repeated
 continuously.
+
+FIXE: Don't call getInstance() twice
+
 ```cpp
-// set the background music and continusously play it.
-SimpleAudioEngine::getInstance()->playBackgroundMusic("mymusic.mp3", true);
+auto audio = SimpleAudioEngine::getInstance();
+
+// set the background music and continuously play it.
+audio->playBackgroundMusic("mymusic.mp3", true);
 
 // set the background music and play it just once.
-SimpleAudioEngine::getInstance()->playBackgroundMusic("mymusic.mp3", false);
+audio->playBackgroundMusic("mymusic.mp3", false);
 ```
 ### Play a sound effect.
-Play a sound effect. 
+Play a sound effect.
 ```cpp
 // play a sound effect, just once.
 SimpleAudioEngine::getInstance()->playEffect("myEffect.mp3", false, 1.0f, 1.0f, 1.0f);
 ```
 
-### Pausing, stopping, resuming music and sound effects 
-After you start to play music and sound effects you might need to pause, 
+### Pausing, stopping, resuming music and sound effects
+After you start to play music and sound effects you might need to pause,
 stop or resume after certain operations. This can be done easily.
 ```cpp
 // pause background music.
@@ -94,15 +105,15 @@ SimpleAudioEngine::getInstance()->resumeAllEffects();
 ```
 
 ### Advanced audio functionality
-There is more to the API that you can take advantage of. Let's go ahead 
+There is more to the API that you can take advantage of. Let's go ahead
 and mention a few more items.
 
 ```cpp
 // setting the volume specifying value as a float
 SimpleAudioEngine::getInstance()->setEffectsVolume(5.0f);
 
 // pre-loading background music and effects. You could pre-load
-// effects, perhaps on app startup so they are already loaded 
+// effects, perhaps on app startup so they are already loaded
 // when you want to use them.
 SimpleAudioEngine::getInstance()->preloadBackgroundMusic("myMusic1.mp3");
 SimpleAudioEngine::getInstance()->preloadBackgroundMusic("myMusic2.mp3");
@@ -114,4 +125,4 @@ SimpleAudioEngine::getInstance()->preloadEffect("myEffect2.mp3");
 // you wont use it anymore in your game. unload it to free up
 // resources.
 SimpleAudioEngine::getInstance()->unloadEffect("myEffect1.mp3");
-```
+```

3.md

@@ -1,58 +1,80 @@
 # Chapter 3: Sprites
 
 ## What are Sprites
-A Sprite is a 2D image that can be animated or transformed by changing the properties
-of it, including `rotation`, `position`, `scale`, `color`, etc.
+A Sprite is a 2D image that can be animated or transformed by changing its properties,
+including `rotation`, `position`, `scale`, `color`, etc.
 
 ## Creating Sprites
-There are different ways to create Sprites depending upon what you need to accomplish. You 
-can create a `Sprite` from a number of graphic formats including: PNG, JPEG, TIFF. PVRv2, 
-PVRv2, ETC1 and others. Let's go through some create methods and talk about each one.
+There are different ways to create Sprites depending upon what you need to accomplish. You
+can create a `Sprite` from a number of graphic formats including: PNG, JPEG, TIFF, and others.
+Let's go through some create methods and talk about each one.
 
 ### Creating a Sprite
-A `Sprite` can be created by specifying a specific image file to use. 
+A `Sprite` can be created by specifying an image file to use.
 
 ```cpp
 auto mySprite = Sprite::create("mysprite.png");
 ```
 
 ![](3/i1.png "")
-This creates a `Sprite` from 'mysprite.png'. The result is a `Sprite` of the graphic you 
-loaded. It has the same width and height. If the file is 200x200 the resulting `Sprite` is 
-the same size. 
 
-### Creating a Sprite From a Rect
-This creates a `Sprite` by specifying a file name and a Rect to use as the selection of 
-what the sprites representation is. `setRect()` is the only way to resize a `Sprite` 
+This creates a `Sprite` using the 'mysprite.png' image. The result is that the
+created `Sprite` uses the whole image. `Sprite` has the same dimensions
+of `mysprite.png`. If the image file is 200x200 the resulting `Sprite` is 200x200.
+
+### Creating a Sprite with a Rect
+
+In the previous example, the created `Sprite` has the same size as the original PNG.
+If you want to create a `Sprite` with only a certain portion of the image file, you can
+do it by specifying a `Rect`.
+
+`Rect` has 4 values: origin x, origin y, width and height.
+
 ```cpp
 auto mySprite = Sprite::create("mysprite.png", Rect(0,0,40,40));
 ```
+
 ![](3/i4.png "")
 
+FIXME: Sprites in screenshot must have same position
+
+FIXME: Explain that `Rect` uses the top-left origin
+
+The result is that we are creating a `Sprite` with only a portion of the PNG.
+In this case, the `Sprite` size will be 40x40.
+
+FIXME: Say that these 2 examples are equivalents for this particular case
+
+```cpp
+auto mySprite = Sprite::create("mysprite.png");
+auto mySprite = Sprite::create("mysprite.png", Rect(0,0,200,200));
+```
+
+
 ## Creating a Sprite from a Sprite Sheet
-A `sprite sheet` a way to combine sprites into a single texture while reducing
-the overall size compared to loading each `Sprite` individually. Why does this
-matter? When loading a `Sprite` each hardware platform has constraints of a 
-minimum texture size that it will need to load. As you can imagine there is 
-a lot of unused space and this increases memory consumption, draw times and 
-lowers your games frame rate. 
-
-Using a `sprite sheet` allows all of your `Sprite` objects to be condensed filing 
-unused space. Now only the entire spritesheet must meet the hardwares constraints 
-and can be loaded all at the same time. This means you will significantly reduce 
-memory usage, reduce the time it takes OpenGL to draw your sprites and keep the 
-frame rate of your game high. Behind the scenes a sprite sheet is a combination 
-of 2 files. The first is a file that describes each `Sprite` in the sprite sheet 
-and its size in `Rect` format. The second is the actual graphic images compacted 
-together fo create as small a file as possible.
-
-When using a `sprite sheet`, it is first loaded, in it's entirety, into the 
-`SpriteFrameCache`. `SpriteFrameCache` is a caching class that retains Sprites 
-quicker future access. This prevents needing to load a `Sprite` multiple times, 
-over and over. The `Sprite` is loaded once and reatined in the `SpriteCache`
+A _sprite sheet_ is a way to combine sprites into a single file. This reduces the
+overall file size compared to having individual files for each `Sprite`. This means
+you will significantly reduce memory usage, file size and loading time.
+
+Also, using sprite sheets is a needed condition in order to achive better performance
+by _batching_ the _draw calls_. More on this in the Advanced Chapter.
+
+When using a `sprite sheet`, it is first loaded, in its entirety, into the
+`SpriteFrameCache`. `SpriteFrameCache` is a caching class that retains `SpriteFrame` for
+future quicker access.
+
+And a `SpriteFrame` is a object that contains the image file name and a `Rect` that
+specifies the size of the sprite.
+
+The `SpriteFrameCache` prevents needing to load a `SpriteFrame` multiple times,
+over and over. The `SpriteFrame` is loaded once and retained in the `SpriteFrameCache`
 
 Here is an example sprite sheet:
 
+FIXME: Low priority. Show a sprite sheet that maximes the space.
+
+FIXME: Horizontal spritesheet is better because it takes less space
+
 ![](3/3_1.png "example SpriteSheet")
 
 Let's tie this all together!
@@ -62,30 +84,40 @@ Load your `sprite sheet` into the `SpriteFrameCache`, probably in `AppDelegate`:
 ```cpp
 // load the Sprite Sheet
 auto spritecache = SpriteFrameCache::getInstance();
+
+// the .pist file can be generated with any of the tools mentioned below
 spritecache->addSpriteFramesWithFile("sprites.plist");
 ```
-Now that we have a `sprite sheet` loaded into `SpriteFrameCache` we can create `Sprite` objects 
+Now that we have a `sprite sheet` loaded into `SpriteFrameCache` we can create `Sprite` objects
 by utilizing it.
 
 ### Creating a Sprite from SpriteFrameCache
-This creates a `Sprite` by pulling it from the `SpriteFrameCache`. 
+This creates a `Sprite` by pulling it from the `SpriteFrameCache`.
 ```cpp
 auto mysprite = Sprite::createWithSpriteFrameName("mysprite.png");
 ```
+
 ![](3/i3.png "")
 
 ### Creating a Sprite from a SpriteFrame
-A `Sprite` can be created from a `SpriteFrame`. A `SpriteFrame` is a specified texture 
-and defined by a specific size `Rect`
+
+Another way to create the same `Sprite` is by fetching the `SpriteFrame` from the
+`SpriteFrameCache`, and then creating the `Sprite` with the `SpriteFrame`.
+Example:
+
 ```cpp
-auto newspriteFrame = SpriteFrame::create("Blue_Front1.png", Rect(0,0,50,50));
-        
+// this is equivalent to the previous example,
+// but you need to type more
+auto newspriteFrame = SpriteFrameCache::getInstance()->getSpriteFrameByName("mysprite.png");
 auto newSprite = Sprite::createWithSpriteFrame(newspriteFrame);
 ```
 ![](3/i2.png "")
 
 ### Tools for creating Sprite Sheets
 
+FIXME: add some text, like... creating spritesheet manually is a tedious work, fortunately
+there are tools that generates them automatically.
+
 [Cocos Studio](http://www.cocos2d-x.org/wiki/CocoStudio)
 
 [Texture Packer](https://www.codeandweb.com/texturepacker)
@@ -101,8 +133,14 @@ auto mySprite = Sprite::create("mysprite.png");
 ```
 ![](3/i1.png "")
 
+FIXME: describe color and opacity then describe the properties first: position, rotation, scale, skew. And then
+describe in more detail what Anchor point is, the coordinate system is uses, etc.
+
 ### Scale
 Changes the *Sprites* scale, either by x, y or uniformly for both x and y.
+
+FIXME: A scale of 2 will take less space for the screenshot
+
 ```cpp
 // increases X and Y size by 4.0 uniformly
 mySprite->setScale(4.0);
@@ -116,7 +154,7 @@ mySprite->setScaleY(4.0);
 ![](3/i5.png "")
 
 ### Anchor Point and Position
-`Anchor Point` is a point that you set as a way of specifying what part of 
+`Anchor Point` is a point that you set as a way of specifying what part of
 the `Sprite` will be used when setting the position of it.
 ```cpp
 // bottom left