From d8a033c2efaf8c6320342f1a926cc7d28c2a8335 Mon Sep 17 00:00:00 2001 From: SuYaohui <365886954@qq.com> Date: Mon, 23 Mar 2015 18:37:28 +0800 Subject: [PATCH] Action,Sprite,TmxTiledMap,UTF8,GLView --- cocos/2d/CCAction.h | 35 ++++--- cocos/2d/CCSprite.h | 26 +++--- cocos/2d/CCTMXTiledMap.h | 190 ++++++++++++++++++++++++++------------ cocos/base/ccUTF8.h | 119 ++++++++++++------------ cocos/platform/CCGLView.h | 183 ++++++++++++++++++++++++++++++------ 5 files changed, 376 insertions(+), 177 deletions(-) diff --git a/cocos/2d/CCAction.h b/cocos/2d/CCAction.h index fd8bf1c802..83ba9e2a86 100644 --- a/cocos/2d/CCAction.h +++ b/cocos/2d/CCAction.h @@ -285,17 +285,15 @@ private: CC_DISALLOW_COPY_AND_ASSIGN(Speed); }; -/** -@brief Follow is an action that "follows" a node. - -Eg: -@code -layer->runAction(Follow::actionWithTarget(hero)); -@endcode - -Instead of using Camera as a "follower", use this action instead. -@since v0.99.2 -*/ +/** @class Follow + * @brief Follow is an action that "follows" a node. + * Eg: + * @code + * layer->runAction(Follow::actionWithTarget(hero)); + * @endcode + * Instead of using Camera as a "follower", use this action instead. + * @since v0.99.2 + */ class CC_DLL Follow : public Action { public: @@ -307,10 +305,21 @@ public: * with no boundary. */ static Follow* create(Node *followedNode, const Rect& rect = Rect::ZERO); - /** Return boundarySet.*/ + /** Return boundarySet. + * + * @return Return boundarySet. + */ inline bool isBoundarySet() const { return _boundarySet; } - /** Alter behavior - turn on/off boundary. */ + /** Alter behavior - turn on/off boundary. + * + * @param value Turn on/off boundary. + */ inline void setBoundarySet(bool value) { _boundarySet = value; } + + /** @deprecated Alter behavior - turn on/off boundary. + * + * @param value Turn on/off boundary. + */ CC_DEPRECATED_ATTRIBUTE inline void setBoudarySet(bool value) { setBoundarySet(value); } // diff --git a/cocos/2d/CCSprite.h b/cocos/2d/CCSprite.h index feeb2a44ea..855580f1d6 100644 --- a/cocos/2d/CCSprite.h +++ b/cocos/2d/CCSprite.h @@ -47,7 +47,7 @@ class Texture2D; struct transformValues_; /** - * @addtogroup sprite_nodes + * @addtogroup _2d * @{ */ @@ -94,7 +94,7 @@ public: * After creation, the rect of sprite will be the size of the image, * and the offset will be (0,0). * - * @param filename A path to image file, e.g., "scene1/monster.png" + * @param filename A path to image file, e.g., "scene1/monster.png". * @return An autoreleased sprite object. */ static Sprite* create(const std::string& filename); @@ -102,9 +102,9 @@ public: /** * Creates a sprite with an image filename and a rect. * - * @param filename A path to image file, e.g., "scene1/monster.png" - * @param rect A subrect of the image file - * @return An autoreleased sprite object + * @param filename A path to image file, e.g., "scene1/monster.png". + * @param rect A subrect of the image file. + * @return An autoreleased sprite object. */ static Sprite* create(const std::string& filename, const Rect& rect); @@ -114,7 +114,7 @@ public: * After creation, the rect will be the size of the texture, and the offset will be (0,0). * * @param texture A pointer to a Texture2D object. - * @return An autoreleased sprite object + * @return An autoreleased sprite object. */ static Sprite* createWithTexture(Texture2D *texture); @@ -170,7 +170,7 @@ public: */ virtual SpriteBatchNode* getBatchNode() const; /** - * Sets the batch node to sprite + * Sets the batch node to sprite. * @warning This method is not recommended for game developers. Sample code for using batch node * @code * SpriteBatchNode *batch = SpriteBatchNode::create("Images/grossini_dance_atlas.png", 15); @@ -268,7 +268,7 @@ public: /** * Whether or not the Sprite needs to be updated in the Atlas. * - * @return true if the sprite needs to be updated in the Atlas, false otherwise. + * @return True if the sprite needs to be updated in the Atlas, false otherwise. */ virtual bool isDirty() const { return _dirty; } @@ -368,21 +368,21 @@ public: /// @} End of Sprite properties getter/setters - /** @deprecated Use isFlippedY() instead */ + /** @deprecated Use isFlippedY() instead. */ CC_DEPRECATED_ATTRIBUTE bool isFlipY() { return isFlippedY(); }; - /** @deprecated Use setFlippedY() instead */ + /** @deprecated Use setFlippedY() instead. */ CC_DEPRECATED_ATTRIBUTE void setFlipY(bool flippedY) { setFlippedY(flippedY); }; // // Overrides // /// @{ - /// @name Functions inherited from TextureProtocol + /// @name Functions inherited from TextureProtocol. /** *@code *When this function bound into js or lua,the parameter will be changed. - *In js: var setBlendFunc(var src, var dst) - *In lua: local setBlendFunc(local src, local dst) + *In js: var setBlendFunc(var src, var dst). + *In lua: local setBlendFunc(local src, local dst). *@endcode */ inline void setBlendFunc(const BlendFunc &blendFunc) override { _blendFunc = blendFunc; } diff --git a/cocos/2d/CCTMXTiledMap.h b/cocos/2d/CCTMXTiledMap.h index 4415ddd073..8bb8d858fb 100644 --- a/cocos/2d/CCTMXTiledMap.h +++ b/cocos/2d/CCTMXTiledMap.h @@ -39,87 +39,100 @@ class TMXTilesetInfo; class TMXMapInfo; /** - * @addtogroup tilemap_parallax_nodes + * @addtogroup _2d * @{ */ -/** Possible orientations of the TMX map */ +/** Possible orientations of the TMX map. */ enum { - /** Orthogonal orientation */ + /** Orthogonal orientation. */ TMXOrientationOrtho, - /** Hexagonal orientation */ + /** Hexagonal orientation. */ TMXOrientationHex, - /** Isometric orientation */ + /** Isometric orientation. */ TMXOrientationIso, - /** Isometric staggered orientation*/ + /** Isometric staggered orientation. */ TMXOrientationStaggered, }; /** @brief TMXTiledMap knows how to parse and render a TMX map. -It adds support for the TMX tiled map format used by http://www.mapeditor.org -It supports isometric, hexagonal and orthogonal tiles. -It also supports object groups, objects, and properties. + * It adds support for the TMX tiled map format used by http://www.mapeditor.org + * It supports isometric, hexagonal and orthogonal tiles. + * It also supports object groups, objects, and properties. -Features: -- Each tile will be treated as an Sprite -- The sprites are created on demand. They will be created only when you call "layer->tileAt(position)" -- Each tile can be rotated / moved / scaled / tinted / "opaqued", since each tile is a Sprite -- Tiles can be added/removed in runtime -- The z-order of the tiles can be modified in runtime -- Each tile has an anchorPoint of (0,0) -- The anchorPoint of the TMXTileMap is (0,0) -- The TMX layers will be added as a child -- The TMX layers will be aliased by default -- The tileset image will be loaded using the TextureCache -- Each tile will have a unique tag -- Each tile will have a unique z value. top-left: z=1, bottom-right: z=max z -- Each object group will be treated as an MutableArray -- Object class which will contain all the properties in a dictionary -- Properties can be assigned to the Map, Layer, Object Group, and Object + * Features: + * - Each tile will be treated as an Sprite. + * - The sprites are created on demand. They will be created only when you call "layer->tileAt(position)". + * - Each tile can be rotated / moved / scaled / tinted / "opaqued", since each tile is a Sprite. + * - Tiles can be added/removed in runtime. + * - The z-order of the tiles can be modified in runtime. + * - Each tile has an anchorPoint of (0,0). + * - The anchorPoint of the TMXTileMap is (0,0). + * - The TMX layers will be added as a child. + * - The TMX layers will be aliased by default. + * - The tileset image will be loaded using the TextureCache. + * - Each tile will have a unique tag. + * - Each tile will have a unique z value. top-left: z=1, bottom-right: z=max z. + * - Each object group will be treated as an MutableArray. + * - Object class which will contain all the properties in a dictionary. + * - Properties can be assigned to the Map, Layer, Object Group, and Object. -Limitations: -- It only supports one tileset per layer. -- Embedded images are not supported -- It only supports the XML format (the JSON format is not supported) + * Limitations: + * - It only supports one tileset per layer. + * - Embedded images are not supported. + * - It only supports the XML format (the JSON format is not supported). -Technical description: -Each layer is created using an TMXLayer (subclass of SpriteBatchNode). If you have 5 layers, then 5 TMXLayer will be created, -unless the layer visibility is off. In that case, the layer won't be created at all. -You can obtain the layers (TMXLayer objects) at runtime by: -- map->getChildByTag(tag_number); // 0=1st layer, 1=2nd layer, 2=3rd layer, etc... -- map->getLayer(name_of_the_layer); + * Technical description: + * Each layer is created using an TMXLayer (subclass of SpriteBatchNode). If you have 5 layers, then 5 TMXLayer will be created, + * unless the layer visibility is off. In that case, the layer won't be created at all. + * You can obtain the layers (TMXLayer objects) at runtime by: + * - map->getChildByTag(tag_number); // 0=1st layer, 1=2nd layer, 2=3rd layer, etc... + * - map->getLayer(name_of_the_layer); -Each object group is created using a TMXObjectGroup which is a subclass of MutableArray. -You can obtain the object groups at runtime by: -- map->getObjectGroup(name_of_the_object_group); + * Each object group is created using a TMXObjectGroup which is a subclass of MutableArray. + * You can obtain the object groups at runtime by: + * - map->getObjectGroup(name_of_the_object_group); -Each object is a TMXObject. + * Each object is a TMXObject. -Each property is stored as a key-value pair in an MutableDictionary. -You can obtain the properties at runtime by: + * Each property is stored as a key-value pair in an MutableDictionary. + * You can obtain the properties at runtime by: -map->getProperty(name_of_the_property); -layer->getProperty(name_of_the_property); -objectGroup->getProperty(name_of_the_property); -object->getProperty(name_of_the_property); + * map->getProperty(name_of_the_property); + * layer->getProperty(name_of_the_property); + * objectGroup->getProperty(name_of_the_property); + * object->getProperty(name_of_the_property); -@since v0.8.1 -*/ + * @since v0.8.1 + */ class CC_DLL TMXTiledMap : public Node { public: - /** creates a TMX Tiled Map with a TMX file.*/ + /** Creates a TMX Tiled Map with a TMX file. + * + * @param tmxFile A TMX file. + * @return An autorelease object. + */ static TMXTiledMap* create(const std::string& tmxFile); - /** initializes a TMX Tiled Map with a TMX formatted XML string and a path to TMX resources */ + /** Initializes a TMX Tiled Map with a TMX formatted XML string and a path to TMX resources. + * + * @param tmxString A TMX formatted XML string. + * @param resourcePath The path to TMX resources. + * @return An autorelease object. + */ static TMXTiledMap* createWithXML(const std::string& tmxString, const std::string& resourcePath); - /** return the TMXLayer for the specific layer */ + /** Return the TMXLayer for the specific layer. + * + * @param layerName A specific layer. + * @return The TMXLayer for the specific layer. + */ TMXLayer* getLayer(const std::string& layerName) const; /** * @js NA @@ -127,7 +140,11 @@ public: */ CC_DEPRECATED_ATTRIBUTE TMXLayer* layerNamed(const std::string& layerName) const { return getLayer(layerName); }; - /** return the TMXObjectGroup for the specific group */ + /** Return the TMXObjectGroup for the specific group. + * + * @param groupName The group Name. + * @return A Type of TMXObjectGroup. + */ TMXObjectGroup* getObjectGroup(const std::string& groupName) const; /** * @js NA @@ -135,7 +152,11 @@ public: */ CC_DEPRECATED_ATTRIBUTE TMXObjectGroup* objectGroupNamed(const std::string& groupName) const { return getObjectGroup(groupName); }; - /** return the value for the specific property name */ + /** Return the value for the specific property name. + * + * @param propertyName The specific property name. + * @return Return the value for the specific property name. + */ Value getProperty(const std::string& propertyName) const; /** * @js NA @@ -143,40 +164,89 @@ public: */ CC_DEPRECATED_ATTRIBUTE Value propertyNamed(const char *propertyName) const { return getProperty(propertyName); }; - /** return properties dictionary for tile GID */ + /** Return properties dictionary for tile GID. + * + * @param GID The tile GID. + * @return Return properties dictionary for tile GID. + */ Value getPropertiesForGID(int GID) const; CC_DEPRECATED_ATTRIBUTE Value propertiesForGID(int GID) const { return getPropertiesForGID(GID); }; /** Assings properties to argument value, returns true if it did found properties - for that GID and did assinged a value, else it returns false. + * for that GID and did assinged a value, else it returns false. + * + * @param GID The tile GID. + * @param value Argument value. + * @return Return true if it did found properties for that GID and did assinged a value, else it returns false. */ bool getPropertiesForGID(int GID, Value** value); - /** the map's size property measured in tiles */ + /** The map's size property measured in tiles. + * + * @return The map's size property measured in tiles. + */ inline const Size& getMapSize() const { return _mapSize; }; + + /** Set the map's size property measured in tiles. + * + * @param mapSize The map's size property measured in tiles. + */ inline void setMapSize(const Size& mapSize) { _mapSize = mapSize; }; - /** the tiles's size property measured in pixels */ + /** The tiles's size property measured in pixels. + * + * @return The tiles's size property measured in pixels. + */ inline const Size& getTileSize() const { return _tileSize; }; + + /** Set the tiles's size property measured in pixels. + * + * @param The tiles's size property measured in pixels. + */ inline void setTileSize(const Size& tileSize) { _tileSize = tileSize; }; - /** map orientation */ + /** Map orientation. + * + * @return Map orientation. + */ inline int getMapOrientation() const { return _mapOrientation; }; + + /** Set map orientation. + * + * @param mapOrientation The map orientation. + */ inline void setMapOrientation(int mapOrientation) { _mapOrientation = mapOrientation; }; - /** object groups */ + /** Get the Object groups. + * + * @return The object groups. + */ inline const Vector& getObjectGroups() const { return _objectGroups; }; inline Vector& getObjectGroups() { return _objectGroups; }; + + /** Set the object groups. + * + * @param groups The object groups. + */ inline void setObjectGroups(const Vector& groups) { _objectGroups = groups; }; - /** properties */ + /** Properties. + * + * @return Properties. + */ inline ValueMap& getProperties() { return _properties; }; + + /** Set the properties. + * + * @param properties A Type of ValueMap to set the properties. + */ inline void setProperties(const ValueMap& properties) { _properties = properties; }; - + + /** Get the description. */ virtual std::string getDescription() const override; CC_CONSTRUCTOR_ACCESS: diff --git a/cocos/base/ccUTF8.h b/cocos/base/ccUTF8.h index bd6e7c831d..a384805bd9 100644 --- a/cocos/base/ccUTF8.h +++ b/cocos/base/ccUTF8.h @@ -35,10 +35,10 @@ NS_CC_BEGIN namespace StringUtils { /** - * @brief Converts utf8 string to utf16 string - * @param utf8 The utf8 string to be converted - * @param outUtf16 The output utf16 string - * @return true if succeed, otherwise false + * @brief Converts utf8 string to utf16 string. + * @param utf8 The utf8 string to be converted. + * @param outUtf16 The output utf16 string. + * @return True if succeed, otherwise false. * @note Please check the return value before using \p outUtf16 * e.g. * @code @@ -52,10 +52,10 @@ namespace StringUtils { CC_DLL bool UTF8ToUTF16(const std::string& utf8, std::u16string& outUtf16); /** - * @brief Converts utf16 string to utf8 string - * @param utf16 The utf16 string to be converted - * @param outUtf8 The output utf8 string - * @return true if succeed, otherwise false + * @brief Converts utf16 string to utf8 string. + * @param utf16 The utf16 string to be converted. + * @param outUtf8 The output utf8 string. + * @return True if succeed, otherwise false. * @note Please check the return value before using \p outUtf8 * e.g. * @code @@ -69,15 +69,14 @@ CC_DLL bool UTF8ToUTF16(const std::string& utf8, std::u16string& outUtf16); CC_DLL bool UTF16ToUTF8(const std::u16string& utf16, std::string& outUtf8); /** - * @brief Trims the unicode spaces at the end of char16_t vector + * @brief Trims the unicode spaces at the end of char16_t vector. */ CC_DLL void trimUTF16Vector(std::vector& str); /** * @brief Whether the character is a whitespace character. - * - * @param ch the unicode character - * @returns whether the character is a white space character. + * @param ch The unicode character. + * @returns Whether the character is a white space character. * * @see http://en.wikipedia.org/wiki/Whitespace_character#Unicode * @@ -86,9 +85,8 @@ CC_DLL bool isUnicodeSpace(char16_t ch); /** * @brief Whether the character is a Chinese/Japanese/Korean character. - * - * @param ch the unicode character - * @returns whether the character is a Chinese character. + * @param ch The unicode character. + * @returns Whether the character is a Chinese character. * * @see http://www.searchtb.com/2012/04/chinese_encode.html * @see http://tieba.baidu.com/p/748765987 @@ -98,39 +96,35 @@ CC_DLL bool isCJKUnicode(char16_t ch); /** * @brief Returns the length of the string in characters. - * - * @param utf8 an UTF-8 encoded string. - * @returns the length of the string in characters + * @param utf8 An UTF-8 encoded string. + * @returns The length of the string in characters. */ CC_DLL long getCharacterCountInUTF8String(const std::string& utf8); /** * @brief Gets the index of the last character that is not equal to the character given. - * - * @param str the string to be searched. - * @param c the character to be searched for. - * - * @returns the index of the last character that is not \p c. - * + * @param str The string to be searched. + * @param c The character to be searched for. + * @returns The index of the last character that is not \p c. */ CC_DLL unsigned int getIndexOfLastNotChar16(const std::vector& str, char16_t c); /** - * @brief Gets char16_t vector from a given utf16 string + * @brief Gets char16_t vector from a given utf16 string. */ CC_DLL std::vector getChar16VectorFromUTF16String(const std::u16string& utf16); } // namespace StringUtils { /** - * Returns the character count in UTF16 string - * @param str pointer to the start of a UTF-16 encoded string. It must be an NULL terminal UTF8 string. - * @deprecated Please use c++11 `std::u16string::length` instead, don't use `unsigned short*` directly + * Returns the character count in UTF16 string. + * @param str Pointer to the start of a UTF-16 encoded string. It must be an NULL terminal UTF8 string. + * @deprecated Please use c++11 `std::u16string::length` instead, don't use `unsigned short*` directly. */ CC_DEPRECATED_ATTRIBUTE CC_DLL int cc_wcslen(const unsigned short* str); -/** Trims the space characters at the end of UTF8 string - * @deprecated Please use `StringUtils::trimUTF16Vector` instead +/** Trims the space characters at the end of UTF8 string. + * @deprecated Please use `StringUtils::trimUTF16Vector` instead. */ CC_DEPRECATED_ATTRIBUTE CC_DLL void cc_utf8_trim_ws(std::vector* str); @@ -138,75 +132,76 @@ CC_DEPRECATED_ATTRIBUTE CC_DLL void cc_utf8_trim_ws(std::vector* /** * Whether the character is a whitespace character. * - * @param ch the unicode character - * @returns whether the character is a white space character. - * @deprecated Please use `StringUtils::isUnicodeSpace` instead + * @param ch The unicode character. + * @returns Whether the character is a white space character. + * @deprecated Please use `StringUtils::isUnicodeSpace` instead. * * @see http://en.wikipedia.org/wiki/Whitespace_character#Unicode - * */ + */ CC_DEPRECATED_ATTRIBUTE CC_DLL bool isspace_unicode(unsigned short ch); /** * Whether the character is a Chinese/Japanese/Korean character. * - * @param ch the unicode character - * @returns whether the character is a Chinese character. - * @deprecated Please use `StringUtils::isCJKUnicode` instead + * @param ch The unicode character + * @returns Whether the character is a Chinese character. + * @deprecated Please use `StringUtils::isCJKUnicode` instead. * * @see http://www.searchtb.com/2012/04/chinese_encode.html * @see http://tieba.baidu.com/p/748765987 - * */ + */ CC_DEPRECATED_ATTRIBUTE CC_DLL bool iscjk_unicode(unsigned short ch); /** * Returns the length of the string in characters. * - * @param p pointer to the start of a UTF-8 encoded string. It must be an NULL terminal UTF8 string. - * @param max Not used from 3.1, just keep it for backward compatibility - * @deprecated Please use `StringUtils::getCharacterCountInUTF8String` instead - * @returns the length of the string in characters + * @param p Pointer to the start of a UTF-8 encoded string. It must be an NULL terminal UTF8 string. + * @param max Not used from 3.1, just keep it for backward compatibility. + * @deprecated Please use `StringUtils::getCharacterCountInUTF8String` instead. + * @returns The length of the string in characters. **/ CC_DEPRECATED_ATTRIBUTE CC_DLL long cc_utf8_strlen (const char * p, int max = -1); /** * Find the last character that is not equal to the character given. * - * @param str the string to be searched. - * @param c the character to be searched for. - * @deprecated Please use `StringUtils::getIndexOfLastNotChar16` instead - * @returns the index of the last character that is not \p c. - * */ + * @param str The string to be searched. + * @param c The character to be searched for. + * @deprecated Please use `StringUtils::getIndexOfLastNotChar16` instead. + * @returns The index of the last character that is not \p c. + */ CC_DEPRECATED_ATTRIBUTE CC_DLL unsigned int cc_utf8_find_last_not_char(const std::vector& str, unsigned short c); /** - * @brief Gets `unsigned short` vector from a given utf16 string - * @deprecated Please use `StringUtils::getChar16VectorFromUTF16String` instead + * @brief Gets `unsigned short` vector from a given utf16 string. + * @param str A given utf16 string. + * @deprecated Please use `StringUtils::getChar16VectorFromUTF16String` instead. */ CC_DEPRECATED_ATTRIBUTE CC_DLL std::vector cc_utf16_vec_from_utf16_str(const unsigned short* str); /** * Creates an utf8 string from a c string. The result will be null terminated. * - * @param str_old pointer to the start of a C string. It must be an NULL terminal UTF8 string. - * @param length not used from 3.1, keep it just for backward compatibility + * @param str_old Pointer to the start of a C string. It must be an NULL terminal UTF8 string. + * @param length Not used from 3.1, keep it just for backward compatibility. * @param rUtf16Size The character count in the return UTF16 string. - * @deprecated Please use `StringUtils::UTF8ToUTF16` instead - * @returns the newly created utf16 string, it must be released with `delete[]`, + * @deprecated Please use `StringUtils::UTF8ToUTF16` instead. + * @returns The newly created utf16 string, it must be released with `delete[]`, * If an error occurs, %NULL will be returned. - * */ + */ CC_DEPRECATED_ATTRIBUTE CC_DLL unsigned short* cc_utf8_to_utf16(const char* str_old, int length = -1, int* rUtf16Size = nullptr); /** * Converts a string from UTF-16 to UTF-8. The result will be null terminated. * - * @param utf16 an UTF-16 encoded string, It must be an NULL terminal UTF16 string. - * @param len not used from 3.1, keep it just for backward compatibility - * @param items_read not used from 3.1, keep it just for backward compatibility - * @param items_written not used from 3.1, keep it just for backward compatibility - * @deprecated Please use `StringUtils::UTF16ToUTF8` instead - * @returns a pointer to a newly allocated UTF-8 string. This value must be + * @param utf16 An UTF-16 encoded string, It must be an NULL terminal UTF16 string. + * @param len Not used from 3.1, keep it just for backward compatibility. + * @param items_read Not used from 3.1, keep it just for backward compatibility. + * @param items_written Not used from 3.1, keep it just for backward compatibility. + * @deprecated Please use `StringUtils::UTF16ToUTF8` instead. + * @returns A pointer to a newly allocated UTF-8 string. This value must be * released with `delete[]`. If an error occurs, %NULL will be returned. - **/ + */ CC_DEPRECATED_ATTRIBUTE CC_DLL char * cc_utf16_to_utf8 (const unsigned short *str, int len = -1, long *items_read = nullptr, @@ -215,4 +210,4 @@ CC_DEPRECATED_ATTRIBUTE CC_DLL char * cc_utf16_to_utf8 (const unsigned short *s NS_CC_END -#endif /* defined(__cocos2dx__ccUTF8__) */ +#endif /** defined(__cocos2dx__ccUTF8__) */ diff --git a/cocos/platform/CCGLView.h b/cocos/platform/CCGLView.h index d89ea87fb3..480a9cbb40 100644 --- a/cocos/platform/CCGLView.h +++ b/cocos/platform/CCGLView.h @@ -39,31 +39,38 @@ THE SOFTWARE. typedef void* id; #endif /* (CC_TARGET_PLATFORM == CC_PLATFORM_MAC) */ +/** There are some Resolution Policy for Adapt to the screen. */ enum class ResolutionPolicy { - // The entire application is visible in the specified area without trying to preserve the original aspect ratio. - // Distortion can occur, and the application may appear stretched or compressed. + /** The entire application is visible in the specified area without trying to preserve the original aspect ratio. + * Distortion can occur, and the application may appear stretched or compressed. + */ EXACT_FIT, - // The entire application fills the specified area, without distortion but possibly with some cropping, - // while maintaining the original aspect ratio of the application. + /** The entire application fills the specified area, without distortion but possibly with some cropping, + * while maintaining the original aspect ratio of the application. + */ NO_BORDER, - // The entire application is visible in the specified area without distortion while maintaining the original - // aspect ratio of the application. Borders can appear on two sides of the application. + /** The entire application is visible in the specified area without distortion while maintaining the original + * aspect ratio of the application. Borders can appear on two sides of the application. + */ SHOW_ALL, - // The application takes the height of the design resolution size and modifies the width of the internal - // canvas so that it fits the aspect ratio of the device - // no distortion will occur however you must make sure your application works on different - // aspect ratios + /** The application takes the height of the design resolution size and modifies the width of the internal + * canvas so that it fits the aspect ratio of the device. + * No distortion will occur however you must make sure your application works on different + * aspect ratios. + */ FIXED_HEIGHT, - // The application takes the width of the design resolution size and modifies the height of the internal - // canvas so that it fits the aspect ratio of the device - // no distortion will occur however you must make sure your application works on different - // aspect ratios + /** The application takes the width of the design resolution size and modifies the height of the internal + * canvas so that it fits the aspect ratio of the device. + * No distortion will occur however you must make sure your application works on different + * aspect ratios. + */ FIXED_WIDTH, UNKNOWN, }; +/** @struct GLContextAttrs Have six opengl Context Attrs. */ struct GLContextAttrs { int redBits; @@ -80,7 +87,9 @@ NS_CC_BEGIN * @addtogroup platform * @{ */ - +/** + * @brief By GLView you can operate the frame information of EGL view through some function. + */ class CC_DLL GLView : public Ref { public: @@ -103,56 +112,100 @@ public: /** Exchanges the front and back buffers, subclass must implement this method. */ virtual void swapBuffers() = 0; - /** Open or close IME keyboard , subclass must implement this method. */ + /** Open or close IME keyboard , subclass must implement this method. + * + * @param open Open or close IME keyboard. + */ virtual void setIMEKeyboardState(bool open) = 0; #if (CC_TARGET_PLATFORM == CC_PLATFORM_WP8 || CC_TARGET_PLATFORM == CC_PLATFORM_WINRT) virtual void setIMEKeyboardState(bool open, std::string str) = 0; #endif + /** When the window is closed, it will return false if the platforms is Ios or Android. + * If the platforms is windows or Mac,it will return true. + * + * @return In ios and android it will return false,if in windows or Mac it will return true. + */ virtual bool windowShouldClose() { return false; }; - //static method and member so that we can modify it on all platforms before create OpenGL context + /** Static method and member so that we can modify it on all platforms before create OpenGL context. + * + * @param glContextAttrs The OpenGL context attrs. + */ static void setGLContextAttrs(GLContextAttrs& glContextAttrs); + + /** Return the OpenGL context attrs. + * + * @return Return the OpenGL context attrs. + */ static GLContextAttrs getGLContextAttrs(); + + /** The OpenGL context attrs. */ static GLContextAttrs _glContextAttrs; - /** + /** @deprecated * Polls input events. Subclass must implement methods if platform * does not provide event callbacks. */ CC_DEPRECATED_ATTRIBUTE virtual void pollInputEvents(); - + + /** Polls the events. */ virtual void pollEvents(); /** * Get the frame size of EGL view. * In general, it returns the screen size since the EGL view is a fullscreen view. + * + * @return The frame size of EGL view. */ virtual const Size& getFrameSize() const; /** * Set the frame size of EGL view. + * + * @param width The width of the fram size. + * @param height The height of the fram size. */ virtual void setFrameSize(float width, float height); - /** Set and get zoom factor for frame. This two methods are for - debugging big resolution (e.g.new ipad) app on desktop.*/ + /** Set zoom factor for frame. This methods are for + * debugging big resolution (e.g.new ipad) app on desktop. + * + * @param zoomFactor The zoom factor for frame. + */ virtual void setFrameZoomFactor(float zoomFactor) {} + + /** Get zoom factor for frame. This methods are for + * debugging big resolution (e.g.new ipad) app on desktop. + * + * @return The zoom factor for frame. + */ virtual float getFrameZoomFactor() const { return 1.0; } + /** * Hide or Show the mouse cursor if there is one. + * + * @param isVisible Hide or Show the mouse cursor if there is one. */ virtual void setCursorVisible(bool isVisible) {} - /** Get retina factor */ + /** Get retina factor. + * + * @return The retina factor. + */ virtual int getRetinaFactor() const { return 1; } - /** only works on ios platform*/ + /** Only works on ios platform. Set Content Scale of the Factor. */ virtual bool setContentScaleFactor(float scaleFactor) { return false; } + + /** Only works on ios platform. Get Content Scale of the Factor. */ virtual float getContentScaleFactor() const { return 1.0; } - /** returns whether or not the view is in Retina Display mode */ + /** Returns whether or not the view is in Retina Display mode. + * + * @return Returns whether or not the view is in Retina Display mode. + */ virtual bool isRetinaDisplay() const { return false; } #if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS) @@ -166,16 +219,22 @@ public: #endif /** * Get the visible area size of opengl viewport. + * + * @return The visible area size of opengl viewport. */ virtual Size getVisibleSize() const; /** * Get the visible origin point of opengl viewport. + * + * @return The visible origin point of opengl viewport. */ virtual Vec2 getVisibleOrigin() const; /** * Get the visible rectangle of opengl viewport. + * + * @return The visible rectangle of opengl viewport. */ virtual Rect getVisibleRect() const; @@ -192,59 +251,125 @@ public: /** Get design resolution size. * Default resolution size is the same as 'getFrameSize'. + * + * @return The design resolution size. */ virtual const Size& getDesignResolutionSize() const; /** * Set opengl view port rectangle with points. + * + * @param x Set the points of x. + * @param y Set the points of y. + * @param w Set the width of the view port + * @param h Set the Height of the view port. */ virtual void setViewPortInPoints(float x , float y , float w , float h); /** * Set Scissor rectangle with points. + * + * @param x Set the points of x. + * @param y Set the points of y. + * @param w Set the width of the view port + * @param h Set the Height of the view port. */ virtual void setScissorInPoints(float x , float y , float w , float h); /** - * Get whether GL_SCISSOR_TEST is enable + * Get whether GL_SCISSOR_TEST is enable. + * + * @return Whether GL_SCISSOR_TEST is enable. */ virtual bool isScissorEnabled(); /** - * Get the current scissor rectangle + * Get the current scissor rectangle. + * + * @return The current scissor rectangle. */ virtual Rect getScissorRect() const; + /** Set the view name. + * + * @param viewname A string will be set to the view as name. + */ virtual void setViewName(const std::string& viewname); + + /** Get the view name. + * + * @return The view name. + */ const std::string& getViewName() const; - /** Touch events are handled by default; if you want to customize your handlers, please override these functions: */ + /** Touch events are handled by default; if you want to customize your handlers, please override this function. + * + * @param num The number of touch. + * @param ids The identity of the touch. + * @param xs The points of x. + * @param ys The points of y. + */ virtual void handleTouchesBegin(int num, intptr_t ids[], float xs[], float ys[]); + + /** Touch events are handled by default; if you want to customize your handlers, please override this function. + * + * @param num The number of touch. + * @param ids The identity of the touch. + * @param xs The points of x. + * @param ys The points of y. + */ virtual void handleTouchesMove(int num, intptr_t ids[], float xs[], float ys[]); + + /** Touch events are handled by default; if you want to customize your handlers, please override this function. + * + * @param num The number of touch. + * @param ids The identity of the touch. + * @param xs The points of x. + * @param ys The points of y. + */ virtual void handleTouchesEnd(int num, intptr_t ids[], float xs[], float ys[]); + + /** Touch events are handled by default; if you want to customize your handlers, please override this function. + * + * @param num The number of touch. + * @param ids The identity of the touch. + * @param xs The points of x. + * @param ys The points of y. + */ virtual void handleTouchesCancel(int num, intptr_t ids[], float xs[], float ys[]); /** * Get the opengl view port rectangle. + * + * @return Return the opengl view port rectangle. */ const Rect& getViewPortRect() const; /** - * Get list of all active touches + * Get list of all active touches. + * + * @return A list of all active touches. */ std::vector getAllTouches() const; /** * Get scale factor of the horizontal direction. + * + * @return Scale factor of the horizontal direction. */ float getScaleX() const; /** * Get scale factor of the vertical direction. + * + * @return Scale factor of the vertical direction. */ float getScaleY() const; - /** returns the current Resolution policy */ + /** Returns the current Resolution policy. + * + * @return The current Resolution policy. + */ ResolutionPolicy getResolutionPolicy() const { return _resolutionPolicy; } #if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)