Lothario
/
axmol
mirror of https://github.com/axmolengine/axmol.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10968 from WenhaiLin/v3-update-document 

[ci skip]Update document
This commit is contained in:
minggo 2015-03-19 10:46:06 +08:00
parent 8306aaaab2 e528531b4b
commit b469f460c7
17 changed files with 698 additions and 301 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
cocos/2d/CCFont.h
View File

@ -33,9 +33,7 @@ NS_CC_BEGIN
class FontAtlas;
// fwd
class FontAtlas;
/// @cond
class CC_DLL Font : public Ref
{
@ -67,7 +65,8 @@ protected:
};
/// @endcond
NS_CC_END
#endif

3
cocos/2d/CCFontAtlas.h
View File

@ -40,6 +40,8 @@ class Texture2D;
class EventCustom;
class EventListenerCustom;
/// @cond
struct FontLetterDefinition
{
unsigned short letteCharUTF16;
@ -128,6 +130,7 @@ protected:
bool _antialiasEnabled;
};
/// @endcond
NS_CC_END

4
cocos/2d/CCFontAtlasCache.h
View File

@ -34,6 +34,8 @@ NS_CC_BEGIN
class FontAtlas;
/// @cond
class CC_DLL FontAtlasCache
{
public:
@ -56,6 +58,8 @@ private:
static std::unordered_map<std::string, FontAtlas *> _atlasMap;
};
/// @endcond
NS_CC_END
#endif

4
cocos/2d/CCFontCharMap.h
View File

@ -30,6 +30,8 @@
NS_CC_BEGIN
/// @cond
class FontCharMap : public Font
{
public:
@ -61,6 +63,8 @@ private:
};
/// @endcond
NS_CC_END
#endif /* defined(_CCFontCharMap_h_) */

4
cocos/2d/CCFontFNT.h
View File

@ -32,6 +32,8 @@ NS_CC_BEGIN
class BMFontConfiguration;
/// @cond FontFNT
class CC_DLL FontFNT : public Font
{
@ -63,6 +65,8 @@ private:
};
/// @endcond
NS_CC_END
#endif /* defined(__cocos2d_libs__CCFontFNT__) */

5
cocos/2d/CCFontFreeType.h
View File

@ -44,9 +44,10 @@
#undef internal
#endif
NS_CC_BEGIN
/// @cond
class CC_DLL FontFreeType : public Font
{
public:
@ -91,6 +92,8 @@ private:
float _outlineSize;
};
/// @endcond
NS_CC_END
#endif

334
cocos/2d/CCLabel.h
View File

@ -1,6 +1,6 @@
/****************************************************************************
Copyright (c) 2013 Zynga Inc.
Copyright (c) 2013-2014 Chukong Technologies Inc.
Copyright (c) 2013-2015 Chukong Technologies Inc.
http://www.cocos2d-x.org
@ -23,7 +23,6 @@
THE SOFTWARE.
****************************************************************************/
#ifndef _COCOS2D_CCLABEL_H_
#define _COCOS2D_CCLABEL_H_
@ -33,22 +32,39 @@
NS_CC_BEGIN
enum class GlyphCollection {
/**
* @addtogroup GUI
* @{
* @addtogroup Label
* @{
*/
/**
* @brief Possible GlyphCollection used by Label.
*
*/
enum class GlyphCollection {
DYNAMIC,
NEHE,
ASCII,
CUSTOM
};
/**
* @brief Possible LabelEffect used by Label.
*
*/
enum class LabelEffect {
NORMAL,
OUTLINE,
SHADOW,
GLOW
};
/**
* @struct TTFConfig
*
*/
typedef struct _ttfConfig
{
std::string fontFilePath;
@ -74,171 +90,347 @@ typedef struct _ttfConfig
}
}TTFConfig;
/**
* @brief Label is a subclass of SpriteBatchNode that knows how to render text labels.
*
* Label can be created with:
* - A true type font file.
* - A bitmap font file.
* - A char map file.
* - The built in system font.
*
* Bitmap Font supported editors:
* - http://glyphdesigner.71squared.com/ (Commercial, Mac OS X)
* - http://www.n4te.com/hiero/hiero.jnlp (Free, Java)
* - http://slick.cokeandcode.com/demos/hiero.jnlp (Free, Java)
* - http://www.angelcode.com/products/bmfont/ (Free, Windows only)
*/
class CC_DLL Label : public SpriteBatchNode, public LabelProtocol
{
public:
static const int DistanceFieldFontSize;
/// @name Creators
/// @{
/**
* Allocates and initializes a Label, with default settings.
*
* @return An automatically released Label object.
*/
static Label* create();
/** Creates a label with an initial string,font[font name or font file],font size, dimension in points, horizontal alignment and vertical alignment.
* @warning It will generate texture by the platform-dependent code
/**
* Allocates and initializes a Label, base on platform-dependent API.
*
* @param text The initial text.
* @param font A font file or a font family name.
* @param fontSize The font size. This value must be > 0.
* @param dimensions
* @param hAlignment The text horizontal alignment.
* @param vAlignment The text vertical alignment.
*
* @warning It will generate texture by the platform-dependent code.
*
* @return An automatically released Label object.
*/
static Label* createWithSystemFont(const std::string& text, const std::string& font, float fontSize,
const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT,
TextVAlignment vAlignment = TextVAlignment::TOP);
/** Creates a label with an initial string,font file,font size, dimension in points, horizontal alignment and vertical alignment.
* @warning Not support font name.
* @warning Cache textures for each different font size or font file.
/**
* Allocates and initializes a Label, base on FreeType2.
*
* @param text The initial text.
* @param fontFilePath A font file.
* @param fontSize The font size. This value must be > 0.
* @param dimensions
* @param hAlignment The text horizontal alignment.
* @param vAlignment The text vertical alignment.
*
* @return An automatically released Label object.
*/
static Label * createWithTTF(const std::string& text, const std::string& fontFile, float fontSize,
static Label * createWithTTF(const std::string& text, const std::string& fontFilePath, float fontSize,
const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT,
TextVAlignment vAlignment = TextVAlignment::TOP);
/** Create a label with TTF configuration
* @warning Not support font name.
* @warning Cache textures for each different font file when enable distance field.
* @warning Cache textures for each different font size or font file when disable distance field.
/**
* Allocates and initializes a Label, base on FreeType2.
*
* @param ttfConfig A pointer to a TTFConfig object.
* @param text The initial text.
* @param hAlignment The text horizontal alignment.
* @param maxLineWidth The max line width.
*
* @return An automatically released Label object.
* @see TTFConfig setTTFConfig setMaxLineWidth
*/
static Label* createWithTTF(const TTFConfig& ttfConfig, const std::string& text, TextHAlignment alignment = TextHAlignment::LEFT, int maxLineWidth = 0);
static Label* createWithTTF(const TTFConfig& ttfConfig, const std::string& text, TextHAlignment hAlignment = TextHAlignment::LEFT, int maxLineWidth = 0);
/* Creates a label with an FNT file,an initial string,horizontal alignment,max line width and the offset of image*/
static Label* createWithBMFont(const std::string& bmfontFilePath, const std::string& text,
const TextHAlignment& alignment = TextHAlignment::LEFT, int maxLineWidth = 0,
/**
* Allocates and initializes a Label, with a bitmap font file.
*
* @param bmfontPath A bitmap font file, it's a FNT format.
* @param text The initial text.
* @param hAlignment Text horizontal alignment.
* @param maxLineWidth The max line width.
* @param imageOffset
*
* @return An automatically released Label object.
* @see setBMFontFilePath setMaxLineWidth
*/
static Label* createWithBMFont(const std::string& bmfontPath, const std::string& text,
const TextHAlignment& hAlignment = TextHAlignment::LEFT, int maxLineWidth = 0,
const Vec2& imageOffset = Vec2::ZERO);
/**
* Allocates and initializes a Label, with char map configuration.
*
* @param charMapFile A char map file, it's a PNG format.
* @param itemWidth The width in points of each element.
* @param itemHeight The height in points of each element.
* @param startCharMap The starting char of the char map.
*
* @return An automatically released Label object.
*/
static Label * createWithCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap);
/**
* Allocates and initializes a Label, with char map configuration.
*
* @param texture A pointer to an existing Texture2D object.
* @param itemWidth The width in points of each element.
* @param itemHeight The height in points of each element.
* @param startCharMap The starting char of the char map.
*
* @return An automatically released Label object.
*/
static Label * createWithCharMap(Texture2D* texture, int itemWidth, int itemHeight, int startCharMap);
/**
* Allocates and initializes a Label, with char map configuration.
*
* @param plistFile A configuration file of char map.
*
* @return An automatically released Label object.
*/
static Label * createWithCharMap(const std::string& plistFile);
/** set TTF configuration for Label */
// end of creators group
/// @}
/// @{
/// @name Font methods
/**
* Sets a new TTF configuration to Label.
* @see `TTFConfig`
*/
virtual bool setTTFConfig(const TTFConfig& ttfConfig);
/**
* Returns the TTF configuration object used by the Label.
* @see `TTFConfig`
*/
virtual const TTFConfig& getTTFConfig() const { return _fontConfig;}
/** Sets a new bitmap font to Label */
virtual bool setBMFontFilePath(const std::string& bmfontFilePath, const Vec2& imageOffset = Vec2::ZERO);
/** Returns the bitmap font used by the Label.*/
const std::string& getBMFontFilePath() const { return _bmFontPath;}
/**
* Sets a new char map configuration to Label.
*
* @see `createWithCharMap(const std::string&,int,int,int)`
*/
virtual bool setCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap);
/**
* Sets a new char map configuration to Label.
*
* @see `createWithCharMap(Texture2D*,int,int,int)`
*/
virtual bool setCharMap(Texture2D* texture, int itemWidth, int itemHeight, int startCharMap);
/**
* Sets a new char map configuration to Label.
*
* @see `createWithCharMap(const std::string&)`
*/
virtual bool setCharMap(const std::string& plistFile);
/* Sets the system font[font name or font file] of label*/
virtual void setSystemFontName(const std::string& systemFont);
/**
* Sets a new system font to Label.
*
* @param font A font file or a font family name.
* @warning
*/
virtual void setSystemFontName(const std::string& font);
/** Returns the system font used by the Label.*/
virtual const std::string& getSystemFontName() const { return _systemFont;}
/* Sets the system font size of label.*/
/* Sets the system font size of Label.*/
virtual void setSystemFontSize(float fontSize);
/** Returns the bitmap font path used by the Label.*/
virtual float getSystemFontSize() const { return _systemFontSize;}
virtual void requestSystemFontRefresh() { _systemFontDirty = true;}
/** changes the string to render
* @warning It is as expensive as changing the string if you haven't set up TTF/BMFont/CharMap for the label.
/**
* @warning This method is not recommended for game developers.
*/
virtual void requestSystemFontRefresh() { _systemFontDirty = true;}
// end of font methods
/// @}
/** Sets the text that this Label is to display.*/
virtual void setString(const std::string& text) override;
/** Return the text the Label is displaying.*/
virtual const std::string& getString() const override { return _originalUTF8String; }
/** Sets the text color of the label
* Only support for TTF and system font
* @warning Different from the color of Node.
int getStringNumLines() const;
int getStringLength() const;
/**
* Sets the text color of Label.
*
* The text color is different from the color of Node.
*
* @warning Limiting use to only when the Label created with true type font or system font.
*/
virtual void setTextColor(const Color4B &color);
/** Returns the text color of this label
* Only support for TTF and system font
* @warning Different from the color of Node.
*/
/** Returns the text color of the Label.*/
const Color4B& getTextColor() const { return _textColor;}
/**
* Enable shadow for the label
* Enable shadow effect to Label.
*
* @todo support blur for shadow effect
* @todo Support blur for shadow effect.
*/
virtual void enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(2,-2), int blurRadius = 0);
/** only support for TTF */
/**
* Enable outline effect to Label.
* @warning Limiting use to only when the Label created with true type font or system font.
*/
virtual void enableOutline(const Color4B& outlineColor,int outlineSize = -1);
/** only support for TTF */
/**
* Enable glow effect to Label.
* @warning Limiting use to only when the Label created with true type font.
*/
virtual void enableGlow(const Color4B& glowColor);
/** disable shadow/outline/glow rendering */
/**
* Disable all effect to Label.
*/
virtual void disableEffect();
/** Sets the Label's text horizontal alignment.*/
void setAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment);}
/** Returns the Label's text horizontal alignment.*/
TextHAlignment getTextAlignment() const { return _hAlignment;}
/** Sets the Label's text alignment.*/
void setAlignment(TextHAlignment hAlignment,TextVAlignment vAlignment);
/** Sets the Label's text horizontal alignment.*/
void setHorizontalAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment); }
/** Returns the Label's text horizontal alignment.*/
TextHAlignment getHorizontalAlignment() const { return _hAlignment; }
/** Sets the Label's text vertical alignment.*/
void setVerticalAlignment(TextVAlignment vAlignment) { setAlignment(_hAlignment,vAlignment); }
/** Returns the Label's text vertical alignment.*/
TextVAlignment getVerticalAlignment() const { return _vAlignment; }
/**
* Specify what happens when a line is too long for Label.
*
* @param breakWithoutSpace Lines are automatically broken between words if this value is false.
*/
void setLineBreakWithoutSpace(bool breakWithoutSpace);
/** Sets the max line width of the label.
* The label's max line width be used for force line breaks if the set value not equal zero.
* The label's width and max line width has not always to be equal.
/**
* Makes the Label at most this line untransformed width.
* The Label's max line width be used for force line breaks if the value not equal zero.
*/
void setMaxLineWidth(float maxLineWidth);
float getMaxLineWidth() { return _maxLineWidth; }
/** Sets the untransformed size of the label.
* The label's width be used for text align if the set value not equal zero.
* The label's max line width will be equal to the same value.
/**
* Makes the Label exactly this untransformed width.
*
* The Label's width be used for text align if the value not equal zero.
*/
void setWidth(float width) { setDimensions(width,_labelHeight);}
float getWidth() const { return _labelWidth; }
/** Sets the untransformed size of the label.
* The label's height be used for text align if the set value not equal zero.
* The text will display of incomplete when the size of label not enough to support display all text.
/**
* Makes the Label exactly this untransformed height.
*
* The Label's height be used for text align if the value not equal zero.
* The text will display of incomplete when the size of Label not enough to support display all text.
*/
void setHeight(float height){ setDimensions(_labelWidth, height); }
float getHeight() const { return _labelHeight; }
/** Sets the untransformed size of the label in a more efficient way. */
/** Sets the untransformed size of the Label in a more efficient way. */
void setDimensions(float width, float height);
const Size& getDimensions() const{ return _labelDimensions;}
/** update content immediately.*/
/** Update content immediately.*/
virtual void updateContent();
/**
* Provides a way to treats each character like a Sprite.
* @warning No support system font.
*/
virtual Sprite * getLetter(int lettetIndex);
/** clip upper and lower margin for reduce height of label.
*/
/** Makes the Label to clip upper and lower margin for reduce height of Label.*/
void setClipMarginEnabled(bool clipEnabled) { _clipEnabled = clipEnabled; }
bool isClipMarginEnabled() const { return _clipEnabled; }
/** Sets the line height of the label
@warning Not support system font
@since v3.2.0
/** Sets the line height of the Label.
* @warning Not support system font.
* @since v3.2.0
*/
void setLineHeight(float height);
/** Returns the line height of this label
@warning Not support system font
/**
* Returns the line height of this Label.
* @warning Not support system font.
* @since v3.2.0
*/
float getLineHeight() const;
/** Sets the additional kerning of the label
@warning Not support system font
@since v3.2.0
/**
* Sets the additional kerning of the Label.
*
* @warning Not support system font.
* @since v3.2.0
*/
void setAdditionalKerning(float space);
/** Returns the additional kerning of this label
@warning Not support system font
@since v3.2.0
/**
* Returns the additional kerning of the Label.
*
* @warning Not support system font.
* @since v3.2.0
*/
float getAdditionalKerning() const;
// string related stuff
int getStringNumLines() const;
int getStringLength() const;
FontAtlas* getFontAtlas() { return _fontAtlas; }
virtual void setBlendFunc(const BlendFunc &blendFunc) override;
@ -275,15 +467,21 @@ public:
CC_DEPRECATED_ATTRIBUTE virtual void setFontDefinition(const FontDefinition& textDefinition);
CC_DEPRECATED_ATTRIBUTE const FontDefinition& getFontDefinition() const { return _fontDefinition; }
/**
* @deprecated Use `getLineHeight` instead.
*/
CC_DEPRECATED_ATTRIBUTE int getCommonLineHeight() const { return (int)getLineHeight();}
CC_CONSTRUCTOR_ACCESS:
/**
* Constructor of Label.
* @js NA
*/
Label(FontAtlas *atlas = nullptr, TextHAlignment hAlignment = TextHAlignment::LEFT,
TextVAlignment vAlignment = TextVAlignment::TOP,bool useDistanceField = false,bool useA8Shader = false);
/**
* Destructor of Label.
* @js NA
* @lua NA
*/
@ -407,7 +605,8 @@ protected:
bool _clipEnabled;
bool _blendFuncDirty;
bool _insideBounds; /// whether or not the sprite was inside bounds the previous frame
/// whether or not the sprite was inside bounds the previous frame
bool _insideBounds;
private:
CC_DISALLOW_COPY_AND_ASSIGN(Label);
@ -415,6 +614,9 @@ private:
friend class LabelTextFormatter;
};
// end group
/// @}
/// @}
NS_CC_END

52
cocos/2d/CCLabelAtlas.h
View File

@ -41,47 +41,53 @@ NS_CC_BEGIN
* @{
*/
/** @brief LabelAtlas is a subclass of AtlasNode.
It can be as a replacement of Label since it is MUCH faster.
LabelAtlas versus Label:
- LabelAtlas is MUCH faster than Label
- LabelAtlas "characters" have a fixed height and width
- LabelAtlas "characters" can be anything you want since they are taken from an image file
A more flexible class is LabelBMFont. It supports variable width characters and it also has a nice editor.
*/
/**
* @class LabelAtlas
* @brief LabelAtlas is a subclass of AtlasNode.
*
* It can be as a replacement of Label since it is MUCH faster.
*
* LabelAtlas versus Label:
* - LabelAtlas is MUCH faster than Label.
* - LabelAtlas "characters" have a fixed height and width.
* - LabelAtlas "characters" can be anything you want since they are taken from an image file.
*
* A more flexible class is LabelBMFont. It supports variable width characters and it also has a nice editor.
*/
class CC_DLL LabelAtlas : public AtlasNode, public LabelProtocol
{
public:
/** creates an empty LabelAtlas, user need to call initWithString(...) later to make this object work properly **/
/**
* Creates an empty LabelAtlas.
* User need to call initWithString(...) later to make this object work properly.
*/
static LabelAtlas* create();
/** creates the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas */
/** Creates the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas. */
static LabelAtlas* create(const std::string& string, const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap);
/** creates the LabelAtlas with a string and a configuration file
@since v2.0
/**
* Creates the LabelAtlas with a string and a configuration file.
* @since v2.0
*/
static LabelAtlas* create(const std::string& string, const std::string& fntFile);
/** initializes the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas */
/** Initializes the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas. */
bool initWithString(const std::string& string, const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap);
/** initializes the LabelAtlas with a string and a configuration file
@since v2.0
/**
* Initializes the LabelAtlas with a string and a configuration file.
* @since v2.0
*/
bool initWithString(const std::string& string, const std::string& fntFile);
/** initializes the LabelAtlas with a string, a texture, the width and height in points of each element and the starting char of the atlas */
/** Initializes the LabelAtlas with a string, a texture, the width and height in points of each element and the starting char of the atlas */
bool initWithString(const std::string& string, Texture2D* texture, int itemWidth, int itemHeight, int startCharMap);
// super methods
virtual void updateAtlasValues() override;
virtual void setString(const std::string &label) override;
virtual const std::string& getString(void) const override;
virtual void updateAtlasValues() override;
virtual std::string getDescription() const override;
#if CC_LABELATLAS_DEBUG_DRAW
@ -112,7 +118,7 @@ protected:
// string to render
std::string _string;
// the first char in the charmap
// the first char in the char map
int _mapStartChar;
};

5
cocos/2d/CCLabelBMFont.h
View File

@ -42,6 +42,8 @@ Use any of these editors to generate BMFonts:
NS_CC_BEGIN
/// @cond
#if defined(__GNUC__) && ((__GNUC__ >= 4) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1)))
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
#elif _MSC_VER >= 1400 //vs 2005 or higher
@ -154,6 +156,9 @@ private:
#elif _MSC_VER >= 1400 //vs 2005 or higher
#pragma warning (pop)
#endif
/// @endcond
NS_CC_END
#endif //__CCBITMAP_FONT_ATLAS_H__

5
cocos/2d/CCLabelTTF.h
View File

@ -37,6 +37,8 @@ NS_CC_BEGIN
#pragma warning (disable: 4996)
#endif
/// @cond
class Label;
/**
@ -173,6 +175,9 @@ protected:
#elif _MSC_VER >= 1400 //vs 2005 or higher
#pragma warning (pop)
#endif
/// @endcond
NS_CC_END
#endif //__CCLABEL_H__

3
cocos/2d/CCLabelTextFormatter.h
View File

@ -32,6 +32,7 @@ NS_CC_BEGIN
class Label;
/// @cond
class CC_DLL LabelTextFormatter
{
public:
@ -42,6 +43,8 @@ public:
};
/// @endcond
NS_CC_END
#endif

185
cocos/audio/include/AudioEngine.h
View File

@ -40,18 +40,28 @@
#undef ERROR
#endif // ERROR
/**
* @addtogroup Audio
* @{
*/
NS_CC_BEGIN
namespace experimental{
/**
* @class AudioProfile
*
* @brief
*/
class EXPORT_DLL AudioProfile
{
public:
//name can't be empty
//Profile name can't be empty.
std::string name;
//The maximum number of simultaneous audio instance.
unsigned int maxInstances;
/* minimum delay in between sounds */
/* Minimum delay in between sounds */
double minDelay;
AudioProfile()
@ -65,14 +75,17 @@ public:
class AudioEngineImpl;
/**
@class AudioEngine
@brief
@note
* @class AudioEngine
*
* @brief Offers a interface to play audio.
*
* @note Make sure to call AudioEngine::end() when the audio engine is not needed anymore to release resources.
*/
class EXPORT_DLL AudioEngine
{
public:
/** AudioState enum,all possible states of an audio instance.*/
enum class AudioState
{
ERROR = -1,
@ -86,132 +99,179 @@ public:
static const float TIME_UNKNOWN;
static bool lazyInit();
/**
* Release related objects
@warning It must be called before the application exit
* Release objects relating to AudioEngine.
*
* @warning It must be called before the application exit.
*/
static void end();
/** Gets the default profile of audio instances
* @return the default profile of audio instances
/**
* Gets the default profile of audio instances.
*
* @return The default profile of audio instances.
*/
static AudioProfile* getDefaultProfile();
/** Play 2d sound
* @param filePath The path of an audio file
* @param loop Whether audio instance loop or not
* @param volume volume value (range from 0.0 to 1.0)
* @param profile a profile for audio instance
* @return an audio ID. It allows you to dynamically change the behavior of an audio instance on the fly.
/**
* Play 2d sound.
*
* @param filePath The path of an audio file.
* @param loop Whether audio instance loop or not.
* @param volume Volume value (range from 0.0 to 1.0).
* @param profile A profile for audio instance. When profile is not specified, default profile will be used.
* @return An audio ID. It allows you to dynamically change the behavior of an audio instance on the fly.
*
* @see `AudioProfile`
*/
static int play2d(const std::string& filePath, bool loop = false, float volume = 1.0f, const AudioProfile *profile = nullptr);
/** Sets whether an audio instance loop or not.
@param audioID an audioID returned by the play2d function
@param loop Whether audio instance loop or not
/**
* Sets whether an audio instance loop or not.
*
* @param audioID An audioID returned by the play2d function.
* @param loop Whether audio instance loop or not.
*/
static void setLoop(int audioID, bool loop);
/** Checks whether an audio instance is loop.
* @param audioID an audioID returned by the play2d function
/**
* Checks whether an audio instance is loop.
*
* @param audioID An audioID returned by the play2d function.
* @return Whether or not an audio instance is loop.
*/
static bool isLoop(int audioID);
/** Sets volume for an audio instance.
* @param audioID an audioID returned by the play2d function
* @param volume volume value (range from 0.0 to 1.0)
/**
* Sets volume for an audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @param volume Volume value (range from 0.0 to 1.0).
*/
static void setVolume(int audioID, float volume);
/** Gets the volume value of an audio instance.
* @param audioID an audioID returned by the play2d function
* @return volume value (range from 0.0 to 1.0)
/**
* Gets the volume value of an audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @return Volume value (range from 0.0 to 1.0).
*/
static float getVolume(int audioID);
/** Pause an audio instance.
* @param audioID an audioID returned by the play2d function
/**
* Pause an audio instance.
*
* @param audioID An audioID returned by the play2d function.
*/
static void pause(int audioID);
/** Pause all playing audio instances */
/** Pause all playing audio instances. */
static void pauseAll();
/** Resume an audio instance.
* @param audioID an audioID returned by the play2d function
/**
* Resume an audio instance.
*
* @param audioID An audioID returned by the play2d function.
*/
static void resume(int audioID);
/** Resume all suspended audio instances */
/** Resume all suspended audio instances. */
static void resumeAll();
/** Stop an audio instance.
* @param audioID an audioID returned by the play2d function
/**
* Stop an audio instance.
*
* @param audioID An audioID returned by the play2d function.
*/
static void stop(int audioID);
/** Stop all audio instances */
/** Stop all audio instances. */
static void stopAll();
/** Sets the current playback position of an audio instance.
* @param audioID an audioID returned by the play2d function
/**
* Sets the current playback position of an audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @return
*/
static bool setCurrentTime(int audioID, float time);
/** Gets the current playback position of an audio instance.
* @param audioID an audioID returned by the play2d function
* @return the current playback position of an audio instance
/**
* Gets the current playback position of an audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @return The current playback position of an audio instance.
*/
static float getCurrentTime(int audioID);
/** Gets the duration of an audio instance.
* @param audioID an audioID returned by the play2d function
* @return the duration of an audio instance
/**
* Gets the duration of an audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @return The duration of an audio instance.
*/
static float getDuration(int audioID);
/** Returns the state of an audio instance.
* @param audioID an audioID returned by the play2d function
* @return the status of an audio instance
/**
* Returns the state of an audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @return The status of an audio instance.
*/
static AudioState getState(int audioID);
/** Register a callback to be invoked when an audio instance has completed playing.
* @param audioID an audioID returned by the play2d function
/**
* Register a callback to be invoked when an audio instance has completed playing.
*
* @param audioID An audioID returned by the play2d function.
* @param callback
*/
static void setFinishCallback(int audioID, const std::function<void(int,const std::string&)>& callback);
/**
* Gets the maximum number of simultaneous audio instance of AudioEngine.
*/
static int getMaxAudioInstance() {return _maxInstances;}
/**
* Sets the maximum number of simultaneous audio instance for AudioEngine.
*
* @param maxInstances The maximum number of simultaneous audio instance.
*/
static bool setMaxAudioInstance(int maxInstances);
/** Uncache the audio data from internal buffer.
* AudioEngine cache audio data on ios platform
/**
* Uncache the audio data from internal buffer.
* AudioEngine cache audio data on ios,mac, and win32 platform.
*
* @warning This can lead to stop related audio first.
* @param filePath The path of an audio file
* @param filePath Audio file path.
*/
static void uncache(const std::string& filePath);
/** Uncache all audio data from internal buffer.
/**
* Uncache all audio data from internal buffer.
*
* @warning All audio will be stopped first.
* @param
*/
static void uncacheAll();
/** Gets the audio profile by id of audio instance.
* @param audioID an audioID returned by the play2d function
* @return the audio profile
/**
* Gets the audio profile by id of audio instance.
*
* @param audioID An audioID returned by the play2d function.
* @return The audio profile.
*/
static AudioProfile* getProfile(int audioID);
/** Gets the audio profile by name.
* @param name name of audio profile
* @return the audio profile
/**
* Gets an audio profile by name.
*
* @param profileName A name of audio profile.
* @return The audio profile.
*/
static AudioProfile* getProfile(const std::string &name);
static AudioProfile* getProfile(const std::string &profileName);
protected:
@ -273,6 +333,7 @@ protected:
}
NS_CC_END
// end audio group
/// @}
#endif // __AUDIO_ENGINE_H_
#endif

167
cocos/audio/include/SimpleAudioEngine.h
View File

@ -1,7 +1,7 @@
/****************************************************************************
Copyright (c) 2010 Steve Oldmeadow
Copyright (c) 2010-2012 cocos2d-x.org
Copyright (c) 2013-2014 Chukong Technologies Inc.
Copyright (c) 2013-2015 Chukong Technologies Inc.
http://www.cocos2d-x.org
@ -37,97 +37,105 @@ THE SOFTWARE.
#define CC_DEPRECATED_ATTRIBUTE
#endif
/**
* @addtogroup Audio
* @{
*/
namespace CocosDenshion {
/**
@class SimpleAudioEngine
@brief Offers a VERY simple interface to play background music & sound effects.
@note Make sure to call SimpleAudioEngine::end() when the sound engine is not needed anymore
to release allocated resources.
* @class SimpleAudioEngine
*
* @brief Offers a very simple interface to play background music & sound effects.
*
* @note Make sure to call SimpleAudioEngine::end() when the sound engine is not needed anymore to release allocated resources.
*/
class EXPORT_DLL SimpleAudioEngine
{
public:
/**
@brief Get the shared Engine object,it will new one when first time be called
* Returns a shared instance of the SimpleAudioEngine.
*/
static SimpleAudioEngine* getInstance();
/**
* @deprecated Use `getInstance` instead.
* @js NA
* @lua NA
*/
CC_DEPRECATED_ATTRIBUTE static SimpleAudioEngine* sharedEngine() { return SimpleAudioEngine::getInstance(); }
/**
@brief Release the shared Engine object
@warning It must be called before the application exit, or a memory leak will be casued.
* Release the shared Engine object.
*
* @warning It must be called before the application exit, or it will lead to memory leaks.
*/
static void end();
protected:
SimpleAudioEngine();
virtual ~SimpleAudioEngine();
public:
/**
@brief Preload background music
@param pszFilePath The path of the background music file.
* Preload background music.
*
* @param filePath The path of the background music file.
* @js preloadMusic
* @lua preloadMusic
*/
virtual void preloadBackgroundMusic(const char* pszFilePath);
virtual void preloadBackgroundMusic(const char* filePath);
/**
@brief Play background music
@param pszFilePath The path of the background music file,or the FileName of T_SoundResInfo
@param bLoop Whether the background music loop or not
* Play background music.
*
* @param filePath The path of the background music file,or the FileName of T_SoundResInfo.
* @param loop Whether the background music loop or not.
* @js playMusic
* @lua playMusic
*/
virtual void playBackgroundMusic(const char* pszFilePath, bool bLoop = false);
virtual void playBackgroundMusic(const char* filePath, bool loop = false);
/**
@brief Stop playing background music
@param bReleaseData If release the background music data or not.As default value is false
* Stop playing background music.
*
* @param releaseData If release the background music data or not.As default value is false.
* @js stopMusic
* @lua stopMusic
*/
virtual void stopBackgroundMusic(bool bReleaseData = false);
virtual void stopBackgroundMusic(bool releaseData = false);
/**
@brief Pause playing background music
* Pause playing background music.
* @js pauseMusic
* @lua pauseMusic
*/
virtual void pauseBackgroundMusic();
/**
@brief Resume playing background music
* Resume playing background music.
* @js resumeMusic
* @lua resumeMusic
*/
virtual void resumeBackgroundMusic();
/**
@brief Rewind playing background music
* Rewind playing background music.
* @js rewindMusic
* @lua rewindMusic
*/
virtual void rewindBackgroundMusic();
/**
@brief Indicates whether any background music can be played or not.
@return <i>true</i> if background music can be played, otherwise <i>false</i>.
* Indicates whether any background music can be played or not.
*
* @return <i>true</i> if background music can be played, otherwise <i>false</i>.
* @js willPlayMusic
* @lua willPlayMusic
*/
virtual bool willPlayBackgroundMusic();
/**
@brief Indicates whether the background music is playing
@return <i>true</i> if the background music is playing, otherwise <i>false</i>
* Indicates whether the background music is playing.
*
* @return <i>true</i> if the background music is playing, otherwise <i>false</i>.
* @js isMusicPlaying
* @lua isMusicPlaying
*/
@ -138,28 +146,30 @@ public:
//
/**
@brief The volume of the background music within the range of 0.0 as the minimum and 1.0 as the maximum.
* The volume of the background music within the range of 0.0 as the minimum and 1.0 as the maximum.
* @js getMusicVolume
* @lua getMusicVolume
*/
virtual float getBackgroundMusicVolume();
/**
@brief Set the volume of background music
@param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum.
* Set the volume of background music.
*
* @param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum.
* @js setMusicVolume
* @lua setMusicVolume
*/
virtual void setBackgroundMusicVolume(float volume);
/**
@brief The volume of the effects within the range of 0.0 as the minimum and 1.0 as the maximum.
* The volume of the effects within the range of 0.0 as the minimum and 1.0 as the maximum.
*/
virtual float getEffectsVolume();
/**
@brief Set the volume of sound effects
@param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum.
* Set the volume of sound effects.
*
* @param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum.
*/
virtual void setEffectsVolume(float volume);
@ -167,68 +177,89 @@ public:
// for sound effects
/**
@brief Play sound effect with a file path, pitch, pan and gain
@param pszFilePath The path of the effect file.
@param bLoop Determines whether to loop the effect playing or not. The default value is false.
@param pitch Frequency, normal value is 1.0. Will also change effect play time.
@param pan Stereo effect, in the range of [-1..1] where -1 enables only left channel.
@param gain Volume, in the range of [0..1]. The normal value is 1.
@return the OpenAL source id
@note Full support is under development, now there are limitations:
- no pitch effect on Samsung Galaxy S2 with OpenSL backend enabled;
- no pitch/pan/gain on emscrippten, win32, marmalade.
* Play sound effect with a file path, pitch, pan and gain.
*
* @param filePath The path of the effect file.
* @param loop Determines whether to loop the effect playing or not. The default value is false.
* @param pitch Frequency, normal value is 1.0. Will also change effect play time.
* @param pan Stereo effect, in the range of [-1..1] where -1 enables only left channel.
* @param gain Volume, in the range of [0..1]. The normal value is 1.
* @return The sound id.
*
* @note Full support is under development, now there are limitations:
* - no pitch effect on Samsung Galaxy S2 with OpenSL backend enabled;
* - no pitch/pan/gain on win32.
*/
virtual unsigned int playEffect(const char* pszFilePath, bool bLoop = false,
virtual unsigned int playEffect(const char* filePath, bool loop = false,
float pitch = 1.0f, float pan = 0.0f, float gain = 1.0f);
/**
@brief Pause playing sound effect
@param nSoundId The return value of function playEffect
* Pause playing sound effect.
*
* @param soundId The return value of function playEffect.
*/
virtual void pauseEffect(unsigned int nSoundId);
virtual void pauseEffect(unsigned int soundId);
/**
@brief Pause all playing sound effect
* Pause all playing sound effect.
*/
virtual void pauseAllEffects();
/**
@brief Resume playing sound effect
@param nSoundId The return value of function playEffect
* Resume playing sound effect.
*
* @param soundId The return value of function playEffect.
*/
virtual void resumeEffect(unsigned int nSoundId);
virtual void resumeEffect(unsigned int soundId);
/**
@brief Resume all playing sound effect
* Resume all playing sound effect.
*/
virtual void resumeAllEffects();
/**
@brief Stop playing sound effect
@param nSoundId The return value of function playEffect
* Stop playing sound effect.
*
* @param soundId The return value of function playEffect.
*/
virtual void stopEffect(unsigned int nSoundId);
virtual void stopEffect(unsigned int soundId);
/**
@brief Stop all playing sound effects
* Stop all playing sound effects.
*/
virtual void stopAllEffects();
/**
@brief preload a compressed audio file
@details the compressed audio will be decoded to wave, then written into an internal buffer in SimpleAudioEngine
@param pszFilePath The path of the effect file
* Preload a compressed audio file.
*
* The compressed audio will be decoded to wave, then written into an internal buffer in SimpleAudioEngine.
*
* @param filePath The path of the effect file.
*/
virtual void preloadEffect(const char* pszFilePath);
virtual void preloadEffect(const char* filePath);
/**
@brief unload the preloaded effect from internal buffer
@param pszFilePath The path of the effect file
* Unload the preloaded effect from internal buffer.
*
* @param filePath The path of the effect file.
*/
virtual void unloadEffect(const char* pszFilePath);
virtual void unloadEffect(const char* filePath);
protected:
/**
* Constructor of SimpleAudioEngine.
*/
SimpleAudioEngine();
/**
* Destructor of SimpleAudioEngine.
*/
virtual ~SimpleAudioEngine();
};
} // end of namespace CocosDenshion
// end audio group
/// @}
#endif // _SIMPLE_AUDIO_ENGINE_H_

65
cocos/base/CCController.h
View File

@ -38,10 +38,15 @@ class EventListenerController;
class EventController;
class EventDispatcher;
/**
* @class Controller
* @brief A Controller object represents a connected physical game controller.
*/
class Controller
{
public:
/** Controllers' standard key
/**
* Controllers' standard key
* Controller receives only standard key which contained within enum Key by default.
*/
enum Key
@ -80,49 +85,89 @@ public:
KEY_MAX
};
/**
* @struct KeyStatus
*
*/
typedef struct _keyStatus
{
/** A Boolean value that indicates whether the key is considered pressed. */
bool isPressed;
/** The value of key.This value is used in conjunction with the isPressed parameter. */
float value;
/** A Boolean value that indicates whether the value of key is analog.
* If isAnalog is true, the key value might be a float from -1 to 1.
* If isAnalog is false, the key value would be contain one number: 0 or 1.
*/
bool isAnalog;
}KeyStatus;
static const int TAG_UNSET = -1;
/**
* Gets all Controller objects.
*/
static const std::vector<Controller*>& getAllController(){ return s_allController;}
/** Gets a controller with its tag
/**
* Gets a Controller object with tag.
*
* @param tag An identifier to find the controller.
* @return A Controller object.
*/
static Controller* getControllerByTag(int tag);
/** To start discovering new controllers
* @warning The API only work on the IOS platform.Empty implementation on Android
/**
* Start discovering new controllers.
*
* @warning The API only work on the IOS platform. Empty implementation on other platform.
*/
static void startDiscoveryController();
/** End the discovery process
* @warning The API only work on the IOS platform.Empty implementation on Android
/**
* Stop the discovery process.
*
* @warning The API only work on the IOS platform.Empty implementation on other platform.
*/
static void stopDiscoveryController();
/**
* Gets the name of this Controller object.
*/
const std::string& getDeviceName() const { return _deviceName;}
/**
* Gets the Controller id.
*/
int getDeviceId() const { return _deviceId;}
/**
* Indicates whether the Controller is connected.
*/
bool isConnected() const;
/**
*
*/
const KeyStatus& getKeyStatus(int keyCode);
/** Activate receives key event from external key. e.g. back,menu.
/**
* Activate receives key event from external key. e.g. back,menu.
* Controller receives only standard key which contained within enum Key by default.
*
* @warning The API only work on the android platform for support diversified game controller.
*
* @param externalKeyCode external key code
* @param receive true if external key event on this controller should be receive, false otherwise.
* @param externalKeyCode External key code.
* @param receive True if external key event on this controller should be receive, false otherwise.
*/
void receiveExternalKeyEvent(int externalKeyCode,bool receive);
/** Changes the tag that is used to identify the controller easily.
/**
* Changes the tag that is used to identify the controller easily.
* @param tag A integer that identifies the controller.
*/
void setTag(int tag) { _controllerTag = tag;}
/**
* Returns a tag that is used to identify the controller easily.
*

3
cocos/base/CCEventController.h
View File

@ -31,6 +31,7 @@
NS_CC_BEGIN
/// @cond EventController
class Controller;
class EventListenerController;
@ -64,7 +65,7 @@ protected:
friend class EventListenerController;
};
/// @endcond EventController
NS_CC_END
#endif /* defined(__cocos2d_libs__EventController__) */

7
cocos/ui/UIVideoPlayer.h
View File

@ -33,6 +33,13 @@ NS_CC_BEGIN
namespace experimental{
namespace ui{
/**
* @class VideoPlayer
* @brief Displays a video file.
*
* @note VideoPlayer displays a video file base on system widget.
* It's mean VideoPlayer displays a video file above all graphical elements of cocos2d-x.
*/
class VideoPlayer : public cocos2d::ui::Widget
{
public:

54
cocos/ui/UIWebView.h
View File

@ -40,6 +40,13 @@ namespace experimental{
class WebViewImpl;
/**
* @class WebView
* @brief A View that displays web pages.
*
* @note WebView displays web pages base on system widget.
* It's mean WebView displays web pages above all graphical elements of cocos2d-x.
*/
class CC_GUI_DLL WebView : public cocos2d::ui::Widget {
public:
/**
@ -49,16 +56,17 @@ public:
/**
* Set javascript interface scheme.
*
* @see #onJsCallback
*/
void setJavascriptInterfaceScheme(const std::string &scheme);
/**
* Sets the main page contents, MIME type, content encoding, and base URL.
*
* @param data The content for the main page.
* @param MIMEType The MIME type of the data.
* @param encoding the encoding of the data.
* @param encoding The encoding of the data.
* @param baseURL The base URL for the content.
*/
void loadData(const cocos2d::Data &data,
@ -66,9 +74,9 @@ public:
const std::string &encoding,
const std::string &baseURL);
/**
* Sets the main page content and base URL.
*
* @param string The content for the main page.
* @param baseURL The base URL for the content.
*/
@ -76,13 +84,15 @@ public:
/**
* Loads the given URL.
* @param url content URL
*
* @param url Content URL.
*/
void loadURL(const std::string &url);
/**
* Loads the given fileName.
* @param fileName content fileName
*
* @param fileName Content fileName.
*/
void loadFile(const std::string &fileName);
@ -98,13 +108,15 @@ public:
/**
* Gets whether this WebView has a back history item.
* @return web view has a back history item.
*
* @return WebView has a back history item.
*/
bool canGoBack();
/**
* Gets whether this WebView has a forward history item.
* @return web view has a forward history item.
*
* @return WebView has a forward history item.
*/
bool canGoForward();
@ -119,7 +131,7 @@ public:
void goForward();
/**
* evaluates JavaScript in the context of the currently displayed page
* Evaluates JavaScript in the context of the currently displayed page.
*/
void evaluateJS(const std::string &js);
@ -128,32 +140,30 @@ public:
*/
void setScalesPageToFit(const bool scalesPageToFit);
virtual void draw(cocos2d::Renderer *renderer, cocos2d::Mat4 const &transform, uint32_t flags) override;
virtual void setVisible(bool visible) override;
typedef std::function<void(WebView *sender, const std::string &url)> ccWebViewCallback;
/**
* Call before a web view begins loading.
*
* @param sender The web view that is about to load new content.
* @param url content URL.
* @param url Content URL.
* @return YES if the web view should begin loading content; otherwise, NO .
*/
void setOnShouldStartLoading(const std::function<bool(WebView *sender, const std::string &url)>& callback);
typedef std::function<void(WebView *sender, const std::string &url)> ccWebViewCallback;
/**
* Call after a web view finishes loading.
*
* @param sender The web view that has finished loading.
* @param url content URL.
* @param url Content URL.
*/
void setOnDidFinishLoading(const ccWebViewCallback& callback);
/**
* Call if a web view failed to load content.
*
* @param sender The web view that has failed loading.
* @param url content URL.
* @param url Content URL.
*/
void setOnDidFailLoading(const ccWebViewCallback& callback);
@ -167,6 +177,10 @@ public:
ccWebViewCallback getOnDidFailLoading()const;
ccWebViewCallback getOnJSCallback()const;
virtual void draw(cocos2d::Renderer *renderer, cocos2d::Mat4 const &transform, uint32_t flags) override;
virtual void setVisible(bool visible) override;
protected:
virtual cocos2d::ui::Widget* createCloneInstance() override;
virtual void copySpecialProperties(Widget* model) override;
@ -180,12 +194,12 @@ protected:
ccWebViewCallback _onJSCallback;
/**
* Default constructor
* Default constructor.
*/
WebView();
/**
* Default destructor
* Default destructor.
*/
virtual ~WebView();