Adds support for rotated textures

Adds documentation to Texture and SpriteSheet

R=abarth@chromium.org

Review URL: https://codereview.chromium.org/1212073002.

examples/game/lib/sprite.dart

@@ -103,11 +103,26 @@ class Sprite extends NodeWithSize {
       }
 
       // Do actual drawing of the sprite
-      canvas.drawImageRect(texture.image, texture.frame, texture.spriteSourceSize, paint);
+      if (texture.rotated) {
+        // Calculate the rotated frame and spriteSourceSize
+        Size originalFrameSize = texture.frame.size;
+        Rect rotatedFrame = new Rect.fromPointAndSize(texture.frame.upperLeft, new Size(originalFrameSize.height, originalFrameSize.width));
+        Point rotatedSpriteSourcePoint = new Point(
+            -texture.spriteSourceSize.top - (texture.spriteSourceSize.bottom - texture.spriteSourceSize.top),
+            texture.spriteSourceSize.left);
+        Rect rotatedSpriteSourceSize = new Rect.fromPointAndSize(rotatedSpriteSourcePoint, new Size(originalFrameSize.height, originalFrameSize.width));
+
+        // Draw the rotated sprite
+        canvas.rotate(-Math.PI/2.0);
+        canvas.drawImageRect(texture.image, rotatedFrame, rotatedSpriteSourceSize, paint);
+      } else {
+        // Draw the sprite
+        canvas.drawImageRect(texture.image, texture.frame, texture.spriteSourceSize, paint);
+      }
     } else {
       // Paint a red square for missing texture
       canvas.drawRect(new Rect.fromLTRB(0.0, 0.0, size.width, size.height),
-          new Paint()..color = const Color.fromARGB(255, 255, 0, 0));
+      new Paint()..color = const Color.fromARGB(255, 255, 0, 0));
     }
     canvas.restore();
   }

examples/game/lib/spritesheet.dart

@@ -1,10 +1,19 @@
 part of sprites;
 
+/// A sprite sheet packs a number of smaller images into a single large image.
+///
+/// The placement of the smaller images are defined by a json file. The larger image and json file is typically created
+/// by a tool such as TexturePacker. The [SpriteSheet] class will take a reference to a larger image and a json string.
+/// From the image and the string the [SpriteSheet] creates a number of [Texture] objects. The names of the frames in
+/// the sprite sheet definition are used to reference the different textures.
 class SpriteSheet {
 
   Image _image;
   Map<String, Texture> _textures = new Map();
 
+  /// Creates a new sprite sheet from an [_image] and a sprite sheet [jsonDefinition].
+  ///
+  ///     var mySpriteSheet = new SpriteSheet(myImage, jsonString);
   SpriteSheet(this._image, String jsonDefinition) {
     assert(_image != null);
     assert(jsonDefinition != null);
@@ -53,7 +62,13 @@ class SpriteSheet {
     return new Point(x.toDouble(), y.toDouble());
   }
 
+  /// The image used by the sprite sheet.
+  ///
+  ///     var spriteSheetImage = mySpriteSheet.image;
   Image get image => _image;
 
+  /// Returns a texture by its name.
+  ///
+  ///     var myTexture = mySpriteSheet["example.png"];
   Texture operator [](String fileName) => _textures[fileName];
 }

examples/game/lib/texture.dart

@@ -1,17 +1,56 @@
 part of sprites;
 
+/// A texture represents a rectangular area of an image and is typically used to draw a sprite to the screen.
+///
+/// Normally you get a reference to a texture from a [SpriteSheet], but you can also create one from an [Image].
 class Texture {
+  /// The image that this texture is a part of.
+  ///
+  ///     var textureImage = myTexture.image;
   final Image image;
+
+  /// The logical size of the texture, before being trimmed by the texture packer.
+  ///
+  ///     var textureSize = myTexture.size;
   final Size size;
+
+  /// The name of the image acts as a tag when acquiring a reference to it.
+  ///
+  ///     myTexture.name = "new_texture_name";
   String name;
+
+  /// The texture was rotated 90 degrees when being packed into a sprite sheet.
+  ///
+  ///     if (myTexture.rotated) drawRotated();
   final bool rotated;
+
+  /// The texture was trimmed when being packed into a sprite sheet.
+  ///
+  ///     bool trimmed = myTexture.trimmed
   final bool trimmed;
 
-  Rect frame;
-  Rect spriteSourceSize;
+  /// The frame of the trimmed texture inside the image.
+  ///
+  ///     Rect frame = myTexture.frame;
+  final Rect frame;
 
+  /// The offset and size of the trimmed texture inside the image.
+  ///
+  /// Position represents the offset from the logical [size], the size of the rect represents the size of the trimmed
+  /// texture.
+  ///
+  ///     Rect spriteSourceSize = myTexture.spriteSourceSize;
+  final Rect spriteSourceSize;
+
+  /// The default pivot point for this texture. When creating a [Sprite] from the texture, this is the pivot point that
+  /// will be used.
+  ///
+  ///     myTexture.pivot = new Point(0.5, 0.5);
   Point pivot;
 
+  /// Creates a new texture from an [Image] object.
+  ///
+  ///     var myTexture = new Texture(myImage);
   Texture(Image image) :
     size = new Size(image.width.toDouble(), image.height.toDouble()),
     image = image,
@@ -26,8 +65,9 @@ class Texture {
                            this.spriteSourceSize, this.pivot) {
   }
 
-  Texture textureFromRect(Rect rect, Point offset, bool rotated) {
-    // TODO: Implement this
-    return null;
-  }
+//  Texture textureFromRect(Rect rect, [String name = null]) {
+//    assert(rect != null);
+//    Rect frame = new Rect.fromLTRB();
+//    return new Texture._fromSpriteFrame(image, name, rect.size, false, false, );
+//  }
 }