~~NOTOC~~

====== Shapes ======

---- dataentry extension ----
author_mail   : hoelt@fovea.cc Jean-Christophe Hoelt
description   : When Starling's Quad isn't enough, this extension comes to rescue.
lastupdate_dt : 2014-12-10
compatible    : v1.1
tags          : vector, graphics, line, circle, disk, ring, polygon, shape
homepage_url  : https://github.com/Fovea/starling-shapes
download_url  : https://github.com/Fovea/starling-shapes/archive/v1.0.0.zip
----


===== Overview =====

Adds vector graphics capabilities to Starling: Disks, Circles, Lines and Polygons.

Copyright 2014, [[http://fovea.cc|Fovea]]

This extension was developed for the game [[http://fovea.cc/shyring|Shyring]]. [[http://fovea.cc/shyring|See it in action]]!

===== Why? =====

Why another extension, when there's already the Starling Graphics Extension?

Well, one draw-back of the Graphics extension is that it doesn't allow to `flatten` your sprites. Which will result in poor performances, especially if you have complex static objects that could have been pre-rendered.

So in short, this extension has less features, but is compatible with `flatten`, which will help you write more efficient code.

If all you need are Lines, Circles and custom Polygons, then do not look any further.

Oh, also to mention: it's way simpler to use!
===== API =====

==== starling.display.Poly4 ====

A Poly4 represents an abitrary 4-sided polygon with a uniform color or a color gradient.

<code as3>
Poly4(p1:Point, p2:Point, p3:Point, p4:Point, color:uint=0xffffff, premultipliedAlpha:Boolean=true)
</code>

It inherits directly from starling.display.Quad, so all fancy coloring options of Quads can be used with Poly4.

Note, hit test only check against the polygon's axis-aligned bounding box.

==== starling.display.Ring ====

A Ring represents a ring (what else?).

<code as3>
Ring(innerRadius:Number, outerRadius:Number, color:uint=0xffffff, premultipliedAlpha:Boolean=true)
</code>

It's built using a set of polygons. Number of vertices is relative to the outer radius.

==== starling.display.Disk ====

A Disk is like a ring but without a hole in the middle.

<code as3>
Disk(radius:Number, color:uint=0xffffff, premultipliedAlpha:Boolean=true)
</code>

It's actually a ring with innerRadius set to 0.

==== starling.display.Line ====

A Line represents a segment with a thickness and uniform color or a color gradient.

<code as3>
Line(from:Point, to:Point, thickness:Number, color:uint, premultipliedAlpha:Boolean = true)
</code>

It inherit from the Poly4 class which means you can setup per-vertex color.
The first two points of the Poly4 are those associated with the `from` point of the Line.
The last two points are associated with the `to` point of the Line.

Note, hit test only check against the polygon's axis-aligned bounding box.

===== Hit tests? =====

Used for example to know if the mouse clicked on the object or not. Bounding box hit tests only check if the
coordinate falls inside the axis-aligned rectangle that covers the object.

If you don't need pixel-perfect hit tests for the Shape you're drawing (or maybe no hit-test at all), then
don't worry.

===== Changelog =====

  * //2014/12/17 09:10//: First public version

===== User Comments =====

//Feel free to edit this part of the page!//