cocos2dx[3.2](8) ——核心類Director/Scene/Layer/Sprite

【核心類】

    導演Director、場景Scene、布景層Layer、精靈Sprite的概念請移步： cocos2dx基礎篇(3)——第一個程序HelloWorld

    導演控制場景，場景控制圖層，圖層控制精靈，精靈控制動作。

    相互之間的關系框架如下圖所示：

    由此看出：

        （1）整個游戲一般只有一個導演。

        （2）一個游戲可以由多個場景組成（菜單界面、游戲界面、游戲結束界面等），但是每次導演只能指導一個場景的運作。

        （3）一個場景可以由多個圖層組成（背景層、道具層、英雄層、怪物層等，每個圖層都可以由多個精靈元素組成（標簽、按鈕、菜單等）。

        （4）對于圖層上的每個精靈元素，一般都附帶相應的動作，可以帶多個動作。如揮刀、使用魔法、跑、跳，以及放大、縮小、旋轉等動作。

【導演Director】

    就和現實中的導演一樣，這里的導演也是起到指導的作用的。導演在這里負責的就是讓不同的場景切換，控制整個游戲的流程，包括開始，繼續，暫停等。以及設置、獲取系統信息，比如調整OpenGL相關的設置，獲取屏幕的大小等。

    和Scene、Layer、Sprite等不同的是，導演類Director是直接繼承Ref類的，而不是Node類。

    繼承關系如下：

    主要函數如下：

//
/** 
	導演類Director主要是用來:
		- 創建一個主窗口
		- 管理場景Scene
	Director 也負責以下: 
		- 初始化 OpenGL 內容
		- 設置 OpenGL 像素格式 (默認值時 RGB565) 
		- 設置 OpenGL 緩存大小 (默認是 0-bit) 
		- 設置 投影 (默認是一個 3D) 
		- 設置 方向 (默認是豎屏Portrait)
  
	Director 是一個單例對象, 標準的調用方法是:
		- Director::getInstance()->methodName(); 
*/

class CC_DLL Director : public Ref
{
/**
 *	獲取單例對象
 */
    //獲取全局唯一的Director實例 , 替代 sharedDirector
	//使用方法：Director::getInstance()->replaceScene(scene);
    static Director* getInstance();
	

/**
 *	場景管理相關
 *		- runWithScene
 *		- pushScene
 *		- popScene , popToRootScene , popToSceneStackLevel
 *		- replaceScene
 *		- pause , resume , end
 *		- getRunningScene , isPaused
 */
	//指定進入Director的主循環運行的場景.
	//ps：僅在運行第一個場景時調用,如果已經存在運行中的場景,不能調用本方法.
	//本方法調用后將調用pushScene方法,然后調用startAnimation.
	void runWithScene(Scene *scene);

	//將運行中的場景暫停,并push到場景堆棧中,運行新的場景.
	void pushScene(Scene *scene);

	//從場景堆棧中pop出一個場景,替換現在正運行的場景,而運行中的場景將被刪除.
	void popScene();

	//從場景堆棧中pop出所有場景,最后一個棧底的場景將替換現在正運行的場景,而運行中的場景將被刪除.
	void popToRootScene();

	//彈出從隊列中的所有場景，直到它到達 level.
	//如果 level 是 0,它將結束 director. 
	//如果 level 是 1, 從隊列中彈出所有的場景，直到只有根場景在隊列中. 
	//如果 level <= 當前的堆棧水平，它不會做任何事情。
 	void popToSceneStackLevel(int level);

	//使用新場景替換當前場景,而運行中的場景將被刪除.
	//PS：舊場景不壓入堆棧,而是直接刪除.
	void replaceScene(Scene *scene);

	void pause(void);                //暫停場景
	void resume(void);               //恢復被暫停的場景
	void end(void);                  //終止執行,釋放運行中的場景. GL view需手動移除.
	
	inline Scene* getRunningScene(); //獲取當前運行的場景
    inline bool isPaused();          //Director 是否被暫停


/**
 *	刷新幀數FPS相關
 *		- setAnimationInterval
 *		- setDisplayStats
 *		- getSecondsPerFrame , getTotalFrames
 */
	//設置程序的FPS值. 即刷新頻率,相連兩幀的時間間隔.
	//如dValue = 1.0/60.0 表示每秒60幀.
    virtual void setAnimationInterval(double interval) = 0;
    inline double getAnimationInterval();

    //是否在左下角顯示 FPS
    inline void setDisplayStats(bool displayStats);
    inline bool isDisplayStats();
	
    //獲取每秒執行幀數
    inline float getSecondsPerFrame()
	
    //從 Director 開機后,總共已經渲染了多少幀
    inline unsigned int getTotalFrames();

	
/**
 *	OpenGL圖形渲染相關
 *		- setOpenGLView
 *		- setProjection
 *		- getTextureCache
 *		- setViewport , setGLDefaultValues , setAlphaBlending , setDepthTest
 */
	//獲取渲染所有東西的GLView
	void setOpenGLView(GLView *openGLView);
	inline GLView* getOpenGLView();

	//設置一個 OpenGL 投影
	//	Projection::_2D           : 設定的二維投影（正投影)
	//	Projection::_3D           : 使用 fovy=60, znear=0.5f and zfar=1500 設置一個3D投影
	//	Projection::CUSTOM        : 投影委托里面它調用 "updateProjection".
	//	Projection::DEFAULT = _3D : 默認投影是 3D 投影
	void setProjection(Projection projection);
	inline Projection getProjection();

	TextureCache* getTextureCache() const; //獲取紋理緩沖
	void setViewport();                    //設置glViewport
	void setGLDefaultValues();             //設置 OpenGL 默認值
	void setAlphaBlending(bool on);        //啟用/禁用 OpenGL alpha 混合
	void setDepthTest(bool on);            //啟用/禁用 OpenGL 深度測試


/**
 *	OpenGL View視圖相關
 *		- getWinSize
 *		- getVisibleSize , getVisibleOrigin
 *		- convertToGL , convertToUI
 */
	//類似手機屏幕的大小
	const Size& getWinSize() const;      //獲取OpenGL view大小,單位點.
	Size getWinSizeInPixels() const;     //獲取OpenGL view大小,單位像素.

	//類似程序的游戲區域
	//如果不調用GLView::setDesignResolutionSize(), 值等于getWinSize
	Size getVisibleSize() const;         //獲取OpenGL View可視區域大小,單位點.
	Vec2 getVisibleOrigin() const;       //獲取可視區域的原點坐標.

	//將UIKit坐標與OpenGL坐標的相互轉換
	//UIKit坐標 ：原點在屏幕的左上角. 從左到右,從上到下.
	//OpenGL坐標：原點在屏幕的左下角. 從左到右,從下到上.
	Vec2 convertToGL(const Vec2& point); //轉為GL坐標
	Vec2 convertToUI(const Vec2& point); //轉為UI坐標


/**
 *	其他操作
 *		- purgeCachedData
 *		- getRenderer
 *		- setDefaultValues
 *		- setScheduler , setActionManager , setEventDispatcher
 */
	void purgeCachedData();                               //移除所有 cocos2d 緩存數據.
	Renderer* getRenderer() const;                        //獲取渲染器(Renderer). v3.0
	void setDefaultValues();                              //設置配置信息的默認值

	void setScheduler(Scheduler* scheduler);              //設置與director關聯的調度器
	void setActionManager(ActionManager* actionManager);  //設置與director關聯的ActionManager
	void setEventDispatcher(EventDispatcher* dispatcher); //設置與director關聯的EventDispatcher. v3.0
	Scheduler* getScheduler() const;
	ActionManager* getActionManager() const;
	EventDispatcher* getEventDispatcher() const;
}
//

【場景Scene】

    Scene是繼承與Node類的。作為場景類，它卻只有函數create。因為場景就像是一個容器，將不同的布景層（Layer）組合在一起，方便管理。

    一個游戲會有很多的場景，比如，主界面，游戲界面，載入界面等等都是一個場景。而每一個場景都是由多個圖層組合在一起，形成一個完整的游戲畫面。

    其實在 cocos2dx基礎篇(3)——第一個程序HelloWorld 中就出現了Scene的創建，以及將HelloWorld布景層放入該Scene中。

    繼承關系如下：

    主要函數如下：

//
class CC_DLL Scene : public Node
{
	static Scene *create();                         //大小和屏幕一樣
	static Scene *createWithSize(const Size& size); //自定義大小
	virtual Scene *getScene() const override;       //覆蓋
};
//

【布景層Layer】

    Layer繼承于Node。Layer不僅繼承了CCNode的所有操作，還附加觸控、重力加速度計、支持鍵盤輸入的事件代理。

    一個布景層(Layer)可以包含多個元素，如標簽(Label)、菜單(Menu)、精靈(Sprite)等等。

    和2.x對比，3.2版本的Layer做了很大的改動：將觸控函數 ccTouch 改為 onTouch ，還棄用了好多加速度計、鍵盤輸入事件相關操作函數。

    并且對于觸控、加速度計、鍵盤輸入的事件回調函數，將通過3.x中新的事件分發機制來完成。

    注意：Layer的錨點默認為(0,0)，即左下角。并且忽略錨點的設置，即使你setAnchorPoint了錨點，Layer的錨點也不會改變，依然是（0,0）。

    繼承關系如下：

    主要函數如下：

//
class CC_DLL Layer : public Node
{
/**
 *	創建布景層
 *		- create
 */
    static Layer *create();


/**
 *	觸控相關
 *		- 單點觸控 onTouch
 *		- 多點觸控 onTouches
 */
	//單點觸控
    virtual bool onTouchBegan(Touch *touch, Event *unused_event); 
    virtual void onTouchMoved(Touch *touch, Event *unused_event); 
    virtual void onTouchEnded(Touch *touch, Event *unused_event); 
    virtual void onTouchCancelled(Touch *touch, Event *unused_event);

	//多點觸控
    virtual void onTouchesBegan(const std::vector<Touch*>& touches, Event *unused_event);
    virtual void onTouchesMoved(const std::vector<Touch*>& touches, Event *unused_event);
    virtual void onTouchesEnded(const std::vector<Touch*>& touches, Event *unused_event);
    virtual void onTouchesCancelled(const std::vector<Touch*>&touches, Event *unused_event);


/**
 *	加速度計相關. 即重力感應.
 *		- Acceleration為加速度計信息
 *		- class Acceleration : public Ref { double x , y , z , timestamp; };
 */
	//加速度計監聽事件回調函數
    virtual void onAcceleration(Acceleration* acc, Event* unused_event);
	
	
/**
 *	鍵盤輸入相關
 *		- KeyCode : 為鍵盤按下了那個鍵.
 *		- 舉例    : KEY_BACKSPACE, KEY_ALT, KEY_F1, KEY_0, KEY_A,...
 *		- 詳情參照: "\cocos\base\CCEventKeyboard.h"
 */
	//按下鍵盤, 監聽事件回調函數
	virtual void onKeyPressed(EventKeyboard::KeyCode keyCode, Event* event);
    //釋放鍵盤, 監聽事件回調函數
	virtual void onKeyReleased(EventKeyboard::KeyCode keyCode, Event* event);
};
//

【精靈Sprite】

    精靈說簡單一點，其實就是一個2D的圖片。并賦予圖片各種屬性以及特性。如大小、顏色、放縮、旋轉、動作等。精靈一般都是放在布景層(Layer)上面的，即一個布景層(Layer)應當有許多的精靈存在。精靈可以用來當做背景、人物、鳥、白云等內容。

    Sprite不僅繼承了Node，還繼承了紋理協議接口TextureProtocol。

    TextureProtocol紋理協議接口主要是負責紋理圖片的管理。

    注意：精靈的錨點默認為(0.5,0.5)，即中心點。

    繼承關系如下：

    主要函數如下：

//
/**
	Sprite定義為二維圖像, 可以通過一個圖像或一個圖像的矩形裁剪部分創建Sprite.

		- 為了優化Sprite渲染，請遵循以下最佳用法：
			- 所有Sprite放入同一個SpriteSheet
			- 所有Sprite使用相同的渲染混合函數(BlendFunc)
			- 使得渲染器(Renderer)自動批量處理("batch")Sprite (將會在一次OpenGL調用內繪制完成)

		- 為了獲得額外5%~10的渲染優化效果，你可以把Sprite作為子節點加入到SpriteBatchNode中， 
		- 但這么做有以下限制：
			- Alias/Antialias屬性屬于SpriteBatchNode，不能單獨設置Sprite的Alias屬性。
			- 渲染混合函數(BlendFunc)屬于SpriteBatchNode，不能單獨設置Sprite的渲染混合函數(BlendFunc)。
			- 不支持ParallaxNode，不過可以使用代理("proxy")Sprite模擬實現。

		- Sprite的子節點只能是其它Sprite(或Sprite的子類)
		- Sprite的默認錨點(anchorPoint)為(0.5, 0.5)。
 */
 
class CC_DLL Sprite : public Node, public TextureProtocol
{
/**
 *	創建方法
 *		- create
 *		- createWithTexture
 *		- createWithSpriteFrame
 */
    static Sprite* create();                                                                    //默認創建空精靈對象
    static Sprite* create(const std::string& filename);                                         //圖片文件(*.png)
    static Sprite* create(const std::string& filename, const Rect& rect);                       //截取圖片文件中某一區域圖片
    static Sprite* createWithTexture(Texture2D *texture);                                       //紋理圖片
    static Sprite* createWithTexture(Texture2D *texture, const Rect& rect, bool rotated=false); //截取紋理圖片中某一區域圖片,是否旋轉
    static Sprite* createWithSpriteFrame(SpriteFrame *spriteFrame);                             //精靈幀. 精靈幀一般從plist中讀取的
    static Sprite* createWithSpriteFrameName(const std::string& spriteFrameName);               //精靈幀的名字



/**
 *	批處理節點BatchNode
 *		- updateTransform
 *		- setBatchNode
 *		- getBatchNode
 */
    virtual void updateTransform(void);                          //更新四個值：position(x,y), rotation, scale
    virtual void setBatchNode(SpriteBatchNode *spriteBatchNode); //設置批節點,不推薦手工調用
    virtual SpriteBatchNode* getBatchNode(void);                 //如果精靈是由批節點渲染，則返回批節點


/**
 *	紋理Texture
 *		- setTexture
 *		- setTextureRect
 */
	//設置精靈的紋理圖片.
    virtual void setTexture(const std::string &filename ); //調用setTextureRect設置Sprite尺寸
    virtual void setTexture(Texture2D *texture) override;  //紋理的矩形尺寸大小不會改變
    virtual Texture2D* getTexture() const override;

	//設置Sprite紋理(texture)的Rect尺寸(rect)、是否旋轉(rotated)、裁剪尺寸(untrimmedSize)。 
	//調用此方法會修改紋理(texture)的坐標和頂點位置
    virtual void setTextureRect(const Rect& rect, bool rotated = false, const Size& untrimmedSize = rect.size); 


/**
 *	精靈幀SpriteFrames & 動畫Animation
 *		- setSpriteFrame
 *		- isFrameDisplayed
 *		- getSpriteFrame
 *		- setDisplayFrameWithAnimationName
 */	
	//設置新的顯示精靈幀. 替代setDisplayFrame
    virtual void setSpriteFrame(const std::string &spriteFrameName);
    virtual void setSpriteFrame(SpriteFrame* newFrame);
	
    //返回精靈幀是否正在顯示
    virtual bool isFrameDisplayed(SpriteFrame *pFrame) const;

    //返回當前顯示的精靈幀. 替代 getDisplayFrame
    virtual SpriteFrame* getSpriteFrame() const;

	//通過動畫幀的第frameIndex那一幀來設置顯示精靈幀
	//動畫幀是從CCAnimationCache中讀取的
    virtual void setDisplayFrameWithAnimationName(const std::string& animationName, ssize_t frameIndex);


/**
 *	精靈屬性相關
 *		- setDirty
 *		- getQuad
 *		- isTextureRectRotated
 *		- setAtlasIndex
 *		- getTextureRect
 *		- setTextureAtlas
 *		- getOffsetPosition
 *		- setFlippedX , setFlippedY
 */
	//設置Sprite在紋理集Atlas中是否需要更新
    virtual void setDirty(bool dirty);
    virtual bool isDirty(void) const;
    
	//返回四個值的信息：坐標(x,y),頂點,顏色
    inline V3F_C4B_T2F_Quad getQuad(void) const;
	
	//判斷紋理是否被旋轉
    inline bool isTextureRectRotated(void) const;

	//設置紋理集(TextureAtlas)的當前使用索引
	//警告: 除非你了解調用此方法的影響，否則不要改變此值
    inline void setAtlasIndex(ssize_t atlasIndex);
    inline ssize_t getAtlasIndex(void) const;

    //返回Sprite的Rect區域信息,單位點
    inline const Rect& getTextureRect(void);

    //如果采用批渲染,設置紋理地圖集
    inline void setTextureAtlas(TextureAtlas *pobTextureAtlas);
    inline TextureAtlas* getTextureAtlas(void);
	
    //獲取偏移值
    inline const Vec2& getOffsetPosition(void) const;

	//設置是否翻轉。
    void setFlippedX(bool flippedX); //設置Sprite是否水平翻轉。替代 setFlipX
    bool isFlippedX(void) const;
    void setFlippedY(bool flippedY); //設置Sprite是否垂直翻轉。替代 setFlipY
    bool isFlippedY(void) const;


/**
 *	繼承于TextureProtocol
 *		- setBlendFunc
 */
	//設置顏色混合模式
    inline void setBlendFunc(const BlendFunc &blendFunc) override;
    inline const BlendFunc& getBlendFunc() const override;


/**
 *	繼承于Node
 *		- Scale , Position , Skew , AnchorPoint , Visible
 *		- addChild , removeChild , reorderChild , sortAllChildren
 *		- draw , setOpacityModifyRGB , isOpacityModifyRGB
 */
	virtual void setScaleX(float scaleX) override;
	virtual void setScaleY(float scaleY) override;
	virtual void setScale(float scaleX, float scaleY) override;
	virtual void setScale(float scale) override;

	virtual void setPosition(const Vec2& pos) override;
	virtual void setPosition(float x, float y) override;
	virtual void setRotation(float rotation) override;
	virtual void setPositionZ(float positionZ) override;

	virtual void setSkewX(float sx) override;
	virtual void setSkewY(float sy) override;
	virtual void setRotationSkewX(float rotationX) override;
	virtual void setRotationSkewY(float rotationY) override;

	virtual void setAnchorPoint(const Vec2& anchor) override;
	virtual void ignoreAnchorPointForPosition(bool value) override;

	virtual void setVisible(bool bVisible) override;

	virtual void addChild(Node *child, int zOrder, int tag) override;
	virtual void addChild(Node *child, int zOrder, const std::string &name) override;
	virtual void removeChild(Node* child, bool cleanup) override;
	virtual void removeAllChildrenWithCleanup(bool cleanup) override;
	virtual void reorderChild(Node *child, int zOrder) override;
	virtual void sortAllChildren() override;

	virtual void draw(Renderer *renderer, const Mat4 &transform, uint32_t flags) override;
	virtual void setOpacityModifyRGB(bool modify) override;
	virtual bool isOpacityModifyRGB(void) const override;
};
//