cocos2d-X 节点（CCTMXLayer.h）API

本文来自http://blog.csdn.net/runaying ，引用必须注明出处！

cocos2d-X 节点（CCTMXLayer.h）API

温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记

//cocos2d-x-3.0alpha0/cocos2dx/tilemap_parallax_nodes/

#ifndef __CCTMX_LAYER_H__
#define __CCTMX_LAYER_H__

#include "CCTMXObjectGroup.h"
#include "base_nodes/CCAtlasNode.h"
#include "sprite_nodes/CCSpriteBatchNode.h"
#include "CCTMXXMLParser.h"
#include "support/data_support/ccCArray.h"
NS_CC_BEGIN

class TMXMapInfo;
class TMXLayerInfo;
class TMXTilesetInfo;
struct _ccCArray;

/**
 * @addtogroup tilemap_parallax_nodes
 * @{
 */

/** @brief TMXLayer 代表 TMX layer.

他是 SpriteBatchNode 的子类.默认情况下 tiles （瓷砖）使用TextureAtlas 呈现。 
如果你在运行时修改了 tile ，tile 将变成一个 sprite，否则没有 sprite 对象被创建.
使用 sprite 对象作为 tiles 的好处是:
- tiles (Sprite) 可以使用一个好的 API rotated/scaled/moved 

如果该 layer 包含一个属性名为“ cc_vertexz的一个整数（可以是正或负） ，
那么所有属于 layer的 tiles 将使用该值作为他们OpenGL顶点Ž的深度。

另一方面，如果“cc_vertexz”属性的值是“automatic”获取的，那么 tiles 也会使用该值作为他们OpenGL顶点Ž的深度。
绘制 tiles 之前，GL_ALPHA_TEST 会被启用，绘制完成后也会禁用他们。使用 alpha 函数会调用：


glAlphaFunc( GL_GREATER, value )

"value"默认值是 0, 但是你可以在 tile 添的 layer 里面，设置 layer 的 "cc_alpha_func"属性.
大多数情况下这个值应该是 0, 但是如果你希望 tiles 是 semi-transparent（半透明）时,你或许希望使用一个不同于 0 的值
, 例如 0.5.

如需进一步信息，请参阅编程指南：:

http://www.cocos2d-iphone.org/wiki/doku.php/prog_guide:tiled_maps

@since v0.8.1
Tiles 可以有一个 额外的 tile 标志.此时只可以水平翻转、垂直翻转 这些标志在 TMXXMLParser.h 里面定义了.

@since 1.1
*/

class CC_DLL TMXLayer : public SpriteBatchNode
{
public:
    /**使用 tilesetInfo 、layerInfo、mapInfo 创建一个  TMXLayer */
    static TMXLayer * create(TMXTilesetInfo *tilesetInfo, TMXLayerInfo *layerInfo, TMXMapInfo *mapInfo);
    /**
     * @js ctor
     */
    TMXLayer();
    /**
     * @js NA
     * @lua NA
     */
    virtual ~TMXLayer();

    /** 使用 tilesetInfo 、layerInfo、mapInfo初始化一个  TMXLayer*/
    bool initWithTilesetInfo(TMXTilesetInfo *tilesetInfo, TMXLayerInfo *layerInfo, TMXMapInfo *);

    /**从内存中释放地图所包含的 tile（瓷砖）.
    除非你想知道 runtime 的tiles 位置，你才可以调用这个方法.
    如果你调用 layer->tileGIDAt() 那么不会释放地图
    */
    void releaseMap();

    /** returns  给定 tile(瓷砖) 坐标位置的 tile (Sprite)。
     returned Sprite 会被添加到 TMXLayer.不要重复添加他.
  Sprite 可以像对待任何其他 sprite ：旋转，缩放，转换，不透明度，颜色等
   你可以通过调用下面函数删除:
    - layer->removeChild(sprite, cleanup);
    - or layer->removeTileAt(Point(x,y));
    */
    Sprite* getTileAt(const Point& tileCoordinate);
    CC_DEPRECATED_ATTRIBUTE Sprite* tileAt(const Point& tileCoordinate) { return getTileAt(tileCoordinate); };
    
    /** returns 给定 tile(瓷砖) 坐标， tile（瓷砖）的 gid ，他也会返回 tile（瓷砖）标志.
     这种方法需要 tele map 一直没有被释放(eg.没有调用 [layer releaseMap])
     */
    unsigned int getTileGIDAt(const Point& tileCoordinate, ccTMXTileFlags* flags = nullptr);
    CC_DEPRECATED_ATTRIBUTE unsigned int tileGIDAt(const Point& tileCoordinate, ccTMXTileFlags* flags = nullptr){
        return getTileGIDAt(tileCoordinate, flags);
    };

    /** 设置给定 tile(瓷砖) 坐标， tile（瓷砖）的 gid(gid = tile global（全局） id).
    tile（瓷砖）GID可以通过以下方式获得使用 "tileGIDAt" 方法或者使用 TMX editor -> Tileset Mgr +1.
     如果瓷砖已经放置在该位置，那么它会被删除。
    */
    void setTileGID(unsigned int gid, const Point& tileCoordinate);

    /** 设置给定 tile(瓷砖) 坐标的 gid (gid = tile global（全局） id).
       tile（瓷砖）GID可以通过以下方式获得使用 "tileGIDAt" 方法或者使用 TMX editor -> Tileset Mgr +1.
     如果瓷砖已经放置在该位置，那么它会被删除。
     
      tile(瓷砖) 标志需要修改以及使用 withFlags
     */

    void setTileGID(unsigned int gid, const Point& tileCoordinate, ccTMXTileFlags flags);

    /** removes 给定 tile(瓷砖) 坐标的 tile(瓷砖) */
    void removeTileAt(const Point& tileCoordinate);

    /** returns 给定 tile(瓷砖) 坐标的位置（以点为单位） */
    Point getPositionAt(const Point& tileCoordinate);
    CC_DEPRECATED_ATTRIBUTE Point positionAt(const Point& tileCoordinate) { return getPositionAt(tileCoordinate); };

    /** return 指定属性名的值 */
    String* getProperty(const char *propertyName) const;
    CC_DEPRECATED_ATTRIBUTE String* propertyNamed(const char *propertyName) const { return getProperty(propertyName); };

    /** 创建 tiles */
    void setupTiles();

    inline const char* getLayerName(){ return _layerName.c_str(); }
    inline void setLayerName(const char *layerName){ _layerName = layerName; }

    /** layer 由多少 tiles （瓷砖）组成 */
    inline const Size& getLayerSize() const { return _layerSize; };
    inline void setLayerSize(const Size& size) { _layerSize = size; };
    
    /** 地图由多少 tile 组成 (tile's (瓷砖)的大小不同返回结果可能会有所不同) */
    inline const Size& getMapTileSize() const { return _mapTileSize; };
    inline void setMapTileSize(const Size& size) { _mapTileSize = size; };
    
    /** 指向地图上 tiles 的指针
     * @js NA
     * @lua NA
     */
    inline unsigned int* getTiles() const { return _tiles; };
    inline void setTiles(unsigned int* tiles) { _tiles = tiles; };
    
    /**  layer 的 Tileset（地形）信息 */
    inline TMXTilesetInfo* getTileSet() const { return _tileSet; };
    inline void setTileSet(TMXTilesetInfo* info) {
        CC_SAFE_RETAIN(info);
        CC_SAFE_RELEASE(_tileSet);
        _tileSet = info;
    };
    
    /** Layer 的方向，和地图方向相同 */
    inline unsigned int getLayerOrientation() const { return _layerOrientation; };
    inline void setLayerOrientation(unsigned int orientation) { _layerOrientation = orientation; };
    
    /** layer 的属性。他们可以添加使用瓷砖*/
    inline Dictionary* getProperties() const { return _properties; };
    inline void setProperties(Dictionary* properties) {
        CC_SAFE_RETAIN(properties);
        CC_SAFE_RELEASE(_properties);
        _properties = properties;
    };
    //
    // Override
    //
    /** TMXLayer 不支持手动添加 Sprite.
     @warning addchild(z, tag); 在 TMXLayer 里面不支持 .可以使用 setTileGID 代替.
     */
    virtual void addChild(Node * child, int zOrder, int tag) override;
    // super method
    void removeChild(Node* child, bool cleanup) override;


private:
    Point getPositionForIsoAt(const Point& pos);
    Point getPositionForOrthoAt(const Point& pos);
    Point getPositionForHexAt(const Point& pos);

    Point calculateLayerOffset(const Point& offset);

    /* 优化方法 */
    Sprite* appendTileForGID(unsigned int gid, const Point& pos);
    Sprite* insertTileForGID(unsigned int gid, const Point& pos);
    Sprite* updateTileForGID(unsigned int gid, const Point& pos);

    /*  layer 识别一些特殊的性质, 例如 cc_vertez */
    void parseInternalProperties();
    void setupTileSprite(Sprite* sprite, Point pos, unsigned int gid);
    Sprite* reusedTileWithRect(Rect rect);
    int getVertexZForPos(const Point& pos);

    // index
    unsigned int atlasIndexForExistantZ(unsigned int z);
    unsigned int atlasIndexForNewZ(int z);
    
protected:
    //!  layer 的名字
    std::string _layerName;
    //! TMX Layer 支持不透明
    unsigned char        _opacity;

    unsigned int        _minGID;
    unsigned int        _maxGID;

    //! 仅在 vertexZ (Z 顶点) 使用时使用
    int                    _vertexZvalue;
    bool                _useAutomaticVertexZ;

    //! 用于优化
    Sprite            *_reusedTile;
    ccCArray            *_atlasIndexArray;
    
    // 用于视网膜显示 
    float               _contentScaleFactor;
    
    /** layer 由多少 tiles （瓷砖）组成*/
    Size _layerSize;
    /**地图由多少 tile 组成 (tile's (瓷砖)的大小不同返回结果可能会有所不同) */
    Size _mapTileSize;
    /** 指向地图上 tiles 的指针*/
    unsigned int* _tiles;
    /** layer 的 Tileset（地形）信息*/
    TMXTilesetInfo* _tileSet;
    /** Layer 的方向，和地图方向相同 */
    unsigned int _layerOrientation;
    /** layer 的属性. 他们可以被添加到 Tiled（瓷砖） */
    Dictionary* _properties;
};

// end of tilemap_parallax_nodes group
/// @}

NS_CC_END

#endif //__CCTMX_LAYER_H__