Vlad Shcherban 559fcbfcb9 * [Lua] Adding Spine atlas parser
* [Corona] Adding ability to load atlas files
* [Corona] Added example of using atlas

# Documentation:

## Lua runtime: `spine.Atlas.parse`

`Atlas.lua` introduces `spine.Atlas.parse(atlasPath, baseDir)` funciton. This function can be use across Lua runtimes to implement their their own image sheet bindings. It will return Array of `Page`s or `nil` if error.

### `Page` properties:
* `name` - filename of the page (`"raptor.png"`)
* `size` - dimmensions of original image (`[1022,1022]`)
* `format` - texture format (`"RGBA8888"`)
* `filter` - filter for texture scalin up and down (`["Linear","Linear"]`)
* `wrap` - wrap modes (`"none"`)
* `regions` - Array of `Region`s on this page

### `Region` properties:
* `name` - region name (`"torso"`)
* `rotate` - is image rotated in texture (`true`)
* `xy` - image frame position on texture (`[610,647]`)
* `size` - image frame size on texture (`[54,91]`)
* `splits` - (optional)
* `pad` - (optional)
* `orig` - original image size (`[54,91]`)
* `offset` - offset if image was trimmed (`[0,0]`)
* `index` - `-1`

## Corona runtime: `spine.GetAtlasSprites`

`spine.lua` introduces `spine.GetAtlasSprites(atlasName, baseDir)`, which returns `Sprites` table. This funciton would parse atlas, locate atlas textures, load them to Corona's image sheets and create convinience bindings and functions. User can use convenience functions, or write own wrappers.

### `Sprites` table
#### Convenience functions:
* `ATLAS_HELPER_createImage` - can be assigned to `skeleton.createImage`
* `ATLAS_HELPER_createMesh` - can be assigned to `skeleton.createMesh`
* `ATLAS_HELPER_setupSkeleton` - use this on skeleton to assing both creation functions (`sprites.setupSkeleton(skeleton)`)

### Region name bindings:
All other elements of `Sprites` table would contain binding `sprites["region_name"] = sheetReference`, where each `sheetReference` contains following elements:

* `frame` - number of frame in image sheet (`42`)
* `region` - reference to `Region` table
* `page` -  reference to `Page` table. `Page` table would also get new property - `sheet`, reference to Corona's image sheet where sprites can be accessed.

As result, to create image for `attachment` code would look something like `display.newImage( sprites[attachment.name].page.sheet, sprites[attachment.name].frame )`. For more rubust example see `ATLAS_HELPER_createImage` in `spine-corona/spine.lua`.

# Known Issues:

* Corona would not work with padded/cropped atlases.
* Possible (but unprobable) name collision with region names and `ATLAS_HELPER_*` functions.
2016-06-23 11:07:12 -04:00

107 lines
3.7 KiB
Lua

-------------------------------------------------------------------------------
-- Spine Runtimes Software License
-- Version 2.3
--
-- Copyright (c) 2013-2015, Esoteric Software
-- All rights reserved.
--
-- You are granted a perpetual, non-exclusive, non-sublicensable and
-- non-transferable license to use, install, execute and perform the Spine
-- Runtimes Software (the "Software") and derivative works solely for personal
-- or internal use. Without the written permission of Esoteric Software (see
-- Section 2 of the Spine Software License Agreement), you may not (a) modify,
-- translate, adapt or otherwise create derivative works, improvements of the
-- Software or develop new applications using the Software or (b) remove,
-- delete, alter or obscure any trademarks or any copyright, trademark, patent
-- or other intellectual property or proprietary rights notices on or in the
-- Software, including any copy thereof. Redistributions in binary or source
-- form must include this license and terms.
--
-- THIS SOFTWARE IS PROVIDED BY ESOTERIC SOFTWARE "AS IS" AND ANY EXPRESS OR
-- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
-- EVENT SHALL ESOTERIC SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-- PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-- WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-- OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-- ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-------------------------------------------------------------------------------
local Atlas = {}
function Atlas.parse(atlasPath, atlasBase)
local function parseIntTuple4( l )
local a,b,c,d = string.match( l , " ? ?%a+: ([+-]?%d+), ?([+-]?%d+), ?([+-]?%d+), ?([+-]?%d+)" )
local a,b,c,d = tonumber( a ), tonumber( b ), tonumber( c ), tonumber( d )
return a and b and c and d and {a, b, c ,d}
end
local function parseIntTuple2( l )
local a,b = string.match( l , " ? ?%a+: ([+-]?%d+), ?([+-]?%d+)" )
local a,b = tonumber( a ), tonumber( b )
return a and b and {a, b}
end
if not atlasPath then
error("Error: " .. atlasPath .. ".atlas" .. " doesn't exist!")
return nil
end
local atlasLines = spine.utils.readFile( atlasPath, atlasBase )
if not atlasLines then
error("Error: " .. atlasPath .. ".atlas" .. " unable to read!")
return nil
end
local pages = {}
local it = string.gmatch(atlasLines, "(.-)\r?\n") -- iterate over lines
for l in it do
if #l == 0 then
l = it()
if l then
local page = { name = l }
l = it()
page.size = parseIntTuple2( l )
if page.size then
l = it()
end
page.format = string.match( l, "%a+: (.+)" )
page.filter = {string.match( it(), "%a+: (.+),(.+)" )}
page.wrap = string.match( it(), "%a+: (.+)" )
page.regions = {}
table.insert( pages, page )
else
break
end
else
local region = {name = l}
region.rotate = string.match( it(), "%a+: (.+)" ) == "true"
region.xy = parseIntTuple2( it() )
region.size = parseIntTuple2( it() )
l = it()
region.splits = parseIntTuple4(l)
if region.splits then
l = it()
region.pad = parseIntTuple4(l)
if region.pad then
l = it()
end
end
region.orig = parseIntTuple2( l )
region.offset = parseIntTuple2( it() )
region.index = tonumber( string.match( it() , "%a+: ([+-]?%d+)" ) )
table.insert( pages[#pages].regions, region )
end
end
return pages
end
return Atlas