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

Merge pull request #11078 from calfjohn/v3 

[ci skip] Add documents for Texture2D\TextureAtlas\TextureCache
This commit is contained in:
minggo 2015-03-23 22:16:56 +08:00
parent e3231db0c0 657f270855
commit 7f60b1cea2
3 changed files with 190 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
cocos/renderer/CCTexture2D.h
View File

@ -53,8 +53,8 @@ class GLProgram;
//CLASS INTERFACES:
/** @brief Texture2D class.
* This class allows to easily create OpenGL 2D textures from images, text or raw data.
/**
* @brief Texture2D class. This class allows to easily create OpenGL 2D textures from images, text or raw data.
* The created Texture2D object will always have power-of-two dimensions.
* Depending on how you create the Texture2D object, the actual image area of the texture might be smaller than the texture dimensions i.e. "contentSize" != (pixelsWide, pixelsHigh) and (maxS, maxT) != (1.0, 1.0).
* Be aware that the content of the generated textures will be upside-down!
@ -152,6 +152,8 @@ public:
public:
/** sets the default pixel format for UIImagescontains alpha channel.
@param format
If the UIImage contains alpha channel, then the options are:
- generate 32-bit textures: Texture2D::PixelFormat::RGBA8888 (default one)
- generate 24-bit textures: Texture2D::PixelFormat::RGB888
@ -170,13 +172,15 @@ public:
*/
static void setDefaultAlphaPixelFormat(Texture2D::PixelFormat format);
/** returns the alpha pixel format
/** Returns the alpha pixel format.
@since v0.8
*/
static Texture2D::PixelFormat getDefaultAlphaPixelFormat();
CC_DEPRECATED_ATTRIBUTE static Texture2D::PixelFormat defaultAlphaPixelFormat() { return Texture2D::getDefaultAlphaPixelFormat(); };
/** treats (or not) PVR files as if they have alpha premultiplied.
/** Treats (or not) PVR files as if they have alpha premultiplied.
@param haveAlphaPremultiplied
Since it is impossible to know at runtime if the PVR images have the alpha channel premultiplied, it is
possible load them as if they have (or not) the alpha channel premultiplied.
@ -199,35 +203,57 @@ public:
*/
virtual ~Texture2D();
/**
Get texutre name, dimensions and coordinates message by a string.
* @js NA
* @lua NA
*/
virtual std::string getDescription() const;
/** release only the gl texture.
/** Release only the gl texture.
* @js NA
* @lua NA
*/
void releaseGLTexture();
/** Initializes with a texture2d with data
/** Initializes with a texture2d with data.
@param data Specifies a pointer to the image data in memory.
@param dataLen The image data length.
@param pixelFormat The image pixelFormat.
@param pixelsWide The image width.
@param pixelsHigh The image height.
@param contentSize The image content size.
* @js NA
* @lua NA
*/
bool initWithData(const void *data, ssize_t dataLen, Texture2D::PixelFormat pixelFormat, int pixelsWide, int pixelsHigh, const Size& contentSize);
/** Initializes with mipmaps */
/** Initializes with mipmaps.
@param mipmaps Specifies a pointer to the image data in memory.
@param mipmapsNum The mipmaps number.
@param pixelFormat The image pixelFormat.
@param pixelsWide The image width.
@param pixelsHigh The image height.
*/
bool initWithMipmaps(MipmapInfo* mipmaps, int mipmapsNum, Texture2D::PixelFormat pixelFormat, int pixelsWide, int pixelsHigh);
/** Update with texture data*/
/** Update with texture data.
@param data Specifies a pointer to the image data in memory.
@param offsetX Specifies a texel offset in the x direction within the texture array.
@param offsetY Specifies a texel offset in the y direction within the texture array.
@param width Specifies the width of the texture subimage.
@param height Specifies the height of the texture subimage.
*/
bool updateWithData(const void *data,int offsetX,int offsetY,int width,int height);
/**
Drawing extensions to make it easy to draw basic quads using a Texture2D object.
These functions require GL_TEXTURE_2D and both GL_VERTEX_ARRAY and GL_TEXTURE_COORD_ARRAY client states to be enabled.
*/
/** draws a texture at a given point */
/** Draws a texture at a given point. */
void drawAtPoint(const Vec2& point);
/** draws a texture inside a rect */
/** Draws a texture inside a rect.*/
void drawInRect(const Rect& rect);
/**
@ -235,24 +261,41 @@ public:
*/
/**
Initializes a texture from a UIImage object.
We will use the format you specified with setDefaultAlphaPixelFormat to convert the image for texture.
NOTE: It will not convert the pvr image file.
@param image An UIImage object.
*/
bool initWithImage(Image * image);
/**
Initializes a texture from a UIImage object.
we will use the format you passed to the function to convert the image format to the texture format.
We will use the format you passed to the function to convert the image format to the texture format.
If you pass PixelFormat::Automatic, we will auto detect the image render type and use that type for texture to render.
@param image An UIImage object.
@param format Texture pixel formats.
**/
bool initWithImage(Image * image, PixelFormat format);
/** Initializes a texture from a string with dimensions, alignment, font name and font size */
/** Initializes a texture from a string with dimensions, alignment, font name and font size.
@param text A null terminated string.
@param fontName The font name.
@param dimensions The font dimension.
@param hAlignment The font horizontal text alignment type.
@param vAlignment The font vertical text alignment type.
*/
bool initWithString(const char *text, const std::string &fontName, float fontSize, const Size& dimensions = Size(0, 0), TextHAlignment hAlignment = TextHAlignment::CENTER, TextVAlignment vAlignment = TextVAlignment::TOP);
/** Initializes a texture from a string using a text definition*/
/** Initializes a texture from a string using a text definition.
@param text A null terminated string.
@param textDefinition A FontDefinition object contains font attributes.
*/
bool initWithString(const char *text, const FontDefinition& textDefinition);
/** sets the min filter, mag filter, wrap s and wrap t texture parameters.
/** Sets the min filter, mag filter, wrap s and wrap t texture parameters.
If the texture size is NPOT (non power of 2), then in can only use GL_CLAMP_TO_EDGE in GL_TEXTURE_WRAP_{S,T}.
@warning Calling this method could allocate additional texture memory.
@ -271,7 +314,7 @@ public:
*/
CC_DEPRECATED_ATTRIBUTE void setTexParameters(const TexParams* texParams) { return setTexParameters(*texParams); };
/** sets antialias texture parameters:
/** Sets antialias texture parameters:
- GL_TEXTURE_MIN_FILTER = GL_LINEAR
- GL_TEXTURE_MAG_FILTER = GL_LINEAR
@ -281,7 +324,7 @@ public:
*/
void setAntiAliasTexParameters();
/** sets alias texture parameters:
/** Sets alias texture parameters:
- GL_TEXTURE_MIN_FILTER = GL_NEAREST
- GL_TEXTURE_MAG_FILTER = GL_NEAREST
@ -298,13 +341,13 @@ public:
*/
void generateMipmap();
/** returns the pixel format.
/** Returns the pixel format.
@since v2.0
*/
const char* getStringForFormat() const;
CC_DEPRECATED_ATTRIBUTE const char* stringForFormat() const { return getStringForFormat(); };
/** returns the bits-per-pixel of the in-memory OpenGL texture
/** Returns the bits-per-pixel of the in-memory OpenGL texture
@since v1.0
*/
unsigned int getBitsPerPixelForFormat() const;
@ -316,40 +359,51 @@ public:
unsigned int getBitsPerPixelForFormat(Texture2D::PixelFormat format) const;
CC_DEPRECATED_ATTRIBUTE unsigned int bitsPerPixelForFormat(Texture2D::PixelFormat format) const { return getBitsPerPixelForFormat(format); };
/** content size */
/** Get content size. */
const Size& getContentSizeInPixels();
/** Whether or not the texture has their Alpha premultiplied. */
bool hasPremultipliedAlpha() const;
/** Whether or not the texture has mip maps.*/
bool hasMipmaps() const;
/** Gets the pixel format of the texture */
/** Gets the pixel format of the texture. */
Texture2D::PixelFormat getPixelFormat() const;
/** Gets the width of the texture in pixels */
/** Gets the width of the texture in pixels. */
int getPixelsWide() const;
/** Gets the height of the texture in pixels */
/** Gets the height of the texture in pixels. */
int getPixelsHigh() const;
/** Gets the texture name */
/** Gets the texture name. */
GLuint getName() const;
/** Gets max S */
/** Gets max S. */
GLfloat getMaxS() const;
/** Sets max S */
/** Sets max S. */
void setMaxS(GLfloat maxS);
/** Gets max T */
/** Gets max T. */
GLfloat getMaxT() const;
/** Sets max T */
/** Sets max T. */
void setMaxT(GLfloat maxT);
/** Get the texture content size.*/
Size getContentSize() const;
/** Set a shader program to the texture.
It's used by drawAtPoint and drawInRect
*/
void setGLProgram(GLProgram* program);
/** Get a shader program from the texture.*/
GLProgram* getGLProgram() const;
public:
/** Get pixel info map, the key-value pairs is PixelFormat and PixelFormatInfo.*/
static const PixelFormatInfoMap& getPixelFormatInfoMap();
private:
@ -425,7 +479,8 @@ protected:
/** whether or not the texture has their Alpha premultiplied */
bool _hasPremultipliedAlpha;
/** whether or not the texture has mip maps*/
bool _hasMipmaps;
/** shader program used by drawAtPoint and drawInRect */

114
cocos/renderer/CCTextureAtlas.h
View File

@ -63,14 +63,20 @@ To render the quads using an interleaved vertex array list, you should modify th
class CC_DLL TextureAtlas : public Ref
{
public:
/** creates a TextureAtlas with an filename and with an initial capacity for Quads.
/** Creates a TextureAtlas with an filename and with an initial capacity for Quads.
* The TextureAtlas capacity can be increased in runtime.
*/
@param file A null terminated string contains the file path.
@param capacity Capacity for Quads.
*/
static TextureAtlas* create(const std::string& file , ssize_t capacity);
/** creates a TextureAtlas with a previously initialized Texture2D object, and
/** Creates a TextureAtlas with a previously initialized Texture2D object, and
* with an initial capacity for n Quads.
* The TextureAtlas capacity can be increased in runtime.
@param texture A texture2D object pointer.
@param capacity Capacity for Quads.
*/
static TextureAtlas* createWithTexture(Texture2D *texture, ssize_t capacity);
/**
@ -83,142 +89,152 @@ public:
*/
virtual ~TextureAtlas();
/** initializes a TextureAtlas with a filename and with a certain capacity for Quads.
/** Initializes a TextureAtlas with a filename and with a certain capacity for Quads.
* The TextureAtlas capacity can be increased in runtime.
*
* WARNING: Do not reinitialize the TextureAtlas because it will leak memory (issue #706)
@attention Do not reinitialize the TextureAtlas because it will leak memory (issue #706).
@param file A null terminated string contains the file path.
@param capacity Capacity for Quads.
*/
bool initWithFile(const std::string& file, ssize_t capacity);
/** initializes a TextureAtlas with a previously initialized Texture2D object, and
/** Initializes a TextureAtlas with a previously initialized Texture2D object, and
* with an initial capacity for Quads.
* The TextureAtlas capacity can be increased in runtime.
*
* WARNING: Do not reinitialize the TextureAtlas because it will leak memory (issue #706)
@attention: Do not reinitialize the TextureAtlas because it will leak memory (issue #706).
@param texture A texture2D object pointer.
@param capacity Capacity for Quads.
*/
bool initWithTexture(Texture2D *texture, ssize_t capacity);
/** updates a Quad (texture, vertex and color) at a certain index
* index must be between 0 and the atlas capacity - 1
/** Updates a Quad (texture, vertex and color) at a certain index.
@param quad Quad that are going to be rendered.
@param index Index must be between 0 and the atlas capacity - 1.
@since v0.8
*/
void updateQuad(V3F_C4B_T2F_Quad* quad, ssize_t index);
/** Inserts a Quad (texture, vertex and color) at a certain index
index must be between 0 and the atlas capacity - 1
@since v0.8
/** Inserts a Quad (texture, vertex and color) at a certain index.
@param quad Quad that are going to be rendered.
@param index Index must be between 0 and the atlas capacity - 1.
@since v0.8
*/
void insertQuad(V3F_C4B_T2F_Quad* quad, ssize_t index);
/** Inserts a c array of quads at a given index
index must be between 0 and the atlas capacity - 1
this method doesn't enlarge the array when amount + index > totalQuads
/** Inserts a c array of quads at a given index.
@param quad Quad that are going to be rendered.
@param index Index must be between 0 and the atlas capacity - 1.
@param amount The quads array amount.
@attention This method doesn't enlarge the array when amount + index > totalQuads.
@since v1.1
*/
void insertQuads(V3F_C4B_T2F_Quad* quads, ssize_t index, ssize_t amount);
/** Removes the quad that is located at a certain index and inserts it at a new index
This operation is faster than removing and inserting in a quad in 2 different steps
@since v0.7.2
/** Removes the quad that is located at a certain index and inserts it at a new index.
This operation is faster than removing and inserting in a quad in 2 different steps.
@since v0.7.2
*/
void insertQuadFromIndex(ssize_t fromIndex, ssize_t newIndex);
/** removes a quad at a given index number.
The capacity remains the same, but the total number of quads to be drawn is reduced in 1
/** Removes a quad at a given index number.
The capacity remains the same, but the total number of quads to be drawn is reduced in 1.
@since v0.7.2
*/
void removeQuadAtIndex(ssize_t index);
/** removes a amount of quads starting from index
/** Removes a amount of quads starting from index.
@since 1.1
*/
void removeQuadsAtIndex(ssize_t index, ssize_t amount);
/** removes all Quads.
/** Removes all Quads.
The TextureAtlas capacity remains untouched. No memory is freed.
The total number of quads to be drawn will be 0
The total number of quads to be drawn will be 0.
@since v0.7.2
*/
void removeAllQuads();
/** resize the capacity of the TextureAtlas.
* The new capacity can be lower or higher than the current one
/** Resize the capacity of the TextureAtlas.
* The new capacity can be lower or higher than the current one.
* It returns true if the resize was successful.
* If it fails to resize the capacity it will return false with a new capacity of 0.
@param capacity Capacity for Quads.
*/
bool resizeCapacity(ssize_t capacity);
/**
Used internally by ParticleBatchNode
don't use this unless you know what you're doing
Used internally by ParticleBatchNode.
don't use this unless you know what you're doing.
@since 1.1
*/
void increaseTotalQuadsWith(ssize_t amount);
/** Moves an amount of quads from oldIndex at newIndex
/** Moves an amount of quads from oldIndex at newIndex.
@since v1.1
*/
void moveQuadsFromIndex(ssize_t oldIndex, ssize_t amount, ssize_t newIndex);
/**
Moves quads from index till totalQuads to the newIndex
Used internally by ParticleBatchNode
This method doesn't enlarge the array if newIndex + quads to be moved > capacity
Moves quads from index till totalQuads to the newIndex.
Used internally by ParticleBatchNode.
This method doesn't enlarge the array if newIndex + quads to be moved > capacity.
@since 1.1
*/
void moveQuadsFromIndex(ssize_t index, ssize_t newIndex);
/**
Ensures that after a realloc quads are still empty
Used internally by ParticleBatchNode
Ensures that after a realloc quads are still empty.
Used internally by ParticleBatchNode.
@since 1.1
*/
void fillWithEmptyQuadsFromIndex(ssize_t index, ssize_t amount);
/** draws n quads
* n can't be greater than the capacity of the Atlas
/** Draws n quads.
* N can't be greater than the capacity of the Atlas.
*/
void drawNumberOfQuads(ssize_t n);
/** draws n quads from an index (offset).
n + start can't be greater than the capacity of the atlas
/** Draws n quads from an index (offset).
N + start can't be greater than the capacity of the atlas.
@since v1.0
*/
void drawNumberOfQuads(ssize_t numberOfQuads, ssize_t start);
/** draws all the Atlas's Quads
/** Draws all the Atlas's Quads.
*/
void drawQuads();
/** listen the event that renderer was recreated on Android
/** Listen the event that renderer was recreated on Android.
*/
void listenRendererRecreated(EventCustom* event);
/** whether or not the array buffer of the VBO needs to be updated*/
/** Whether or not the array buffer of the VBO needs to be updated.*/
inline bool isDirty(void) { return _dirty; }
/** specify if the array buffer of the VBO needs to be updated */
/** Specify if the array buffer of the VBO needs to be updated. */
inline void setDirty(bool bDirty) { _dirty = bDirty; }
/**
/**Get quads total amount.
* @js NA
* @lua NA
*/
virtual std::string getDescription() const;
/** Gets the quantity of quads that are going to be drawn */
/** Gets the quantity of quads that are going to be drawn. */
ssize_t getTotalQuads() const;
/** Gets the quantity of quads that can be stored with the current texture atlas size */
/** Gets the quantity of quads that can be stored with the current texture atlas size. */
ssize_t getCapacity() const;
/** Gets the texture of the texture atlas */
/** Gets the texture of the texture atlas. */
Texture2D* getTexture() const;
/** Sets the texture for the texture atlas */
/** Sets the texture for the texture atlas. */
void setTexture(Texture2D* texture);
/** Gets the quads that are going to be rendered */
/** Gets the quads that are going to be rendered. */
V3F_C4B_T2F_Quad* getQuads();
/** Sets the quads that are going to be rendered */
/** Sets the quads that are going to be rendered. */
void setQuads(V3F_C4B_T2F_Quad* quads);
private:

78
cocos/renderer/CCTextureCache.h
View File

@ -53,34 +53,34 @@ NS_CC_BEGIN
* @{
*/
/*
* from version 3.0, TextureCache will never to treated as a singleton, it will be owned by director.
* all call by TextureCache::getInstance() should be replaced by Director::getInstance()->getTextureCache()
* From version 3.0, TextureCache will never to treated as a singleton, it will be owned by director.
* All call by TextureCache::getInstance() should be replaced by Director::getInstance()->getTextureCache().
*/
/** @brief Singleton that handles the loading of textures
* Once the texture is loaded, the next time it will return
* a reference of the previously loaded texture reducing GPU & CPU memory
/** @brief Singleton that handles the loading of textures.
* Once the texture is loaded, the next time it will return.
* A reference of the previously loaded texture reducing GPU & CPU memory.
*/
class CC_DLL TextureCache : public Ref
{
public:
/** Returns the shared instance of the cache */
/** Returns the shared instance of the cache. */
CC_DEPRECATED_ATTRIBUTE static TextureCache * getInstance();
/** @deprecated Use getInstance() instead */
/** @deprecated Use getInstance() instead. */
CC_DEPRECATED_ATTRIBUTE static TextureCache * sharedTextureCache();
/** purges the cache. It releases the retained instance.
/** Purges the cache. It releases the retained instance.
@since v0.99.0
*/
CC_DEPRECATED_ATTRIBUTE static void destroyInstance();
/** @deprecated Use destroyInstance() instead */
/** @deprecated Use destroyInstance() instead. */
CC_DEPRECATED_ATTRIBUTE static void purgeSharedTextureCache();
/** Reload all textures
should not call it, called by frame work
now the function do nothing, use VolatileTextureMgr::reloadAllTextures
/** Reload all textures.
Should not call it, called by frame work.
Now the function do nothing, use VolatileTextureMgr::reloadAllTextures.
*/
CC_DEPRECATED_ATTRIBUTE static void reloadAllTextures();
@ -103,30 +103,34 @@ public:
// Dictionary* snapshotTextures();
/** Returns a Texture2D object given an filename.
* If the filename was not previously loaded, it will create a new Texture2D
* object and it will return it. It will use the filename as a key.
* If the filename was not previously loaded, it will create a new Texture2D.
* Object and it will return it. It will use the filename as a key.
* Otherwise it will return a reference of a previously loaded image.
* Supported image extensions: .png, .bmp, .tiff, .jpeg, .pvr
* Supported image extensions: .png, .bmp, .tiff, .jpeg, .pvr.
@param filepath A null terminated string.
*/
Texture2D* addImage(const std::string &filepath);
/* Returns a Texture2D object given a file image
/** Returns a Texture2D object given a file image.
* If the file image was not previously loaded, it will create a new Texture2D object and it will return it.
* Otherwise it will load a texture in a new thread, and when the image is loaded, the callback will be called with the Texture2D as a parameter.
* The callback will be called from the main thread, so it is safe to create any cocos2d object from the callback.
* Supported image extensions: .png, .jpg
* @since v0.8
@param filepath A null terminated string.
@param callback A callback function would be inovked after the image is loaded.
@since v0.8
*/
virtual void addImageAsync(const std::string &filepath, const std::function<void(Texture2D*)>& callback);
/* Unbind a specified bound image asynchronous callback
/** Unbind a specified bound image asynchronous callback.
* In the case an object who was bound to an image asynchronous callback was destroyed before the callback is invoked,
* the object always need to unbind this callback manually.
* @param filename It's the related/absolute path of the file image.
* @since v3.1
*/
virtual void unbindImageAsync(const std::string &filename);
/* Unbind all bound image asynchronous load callbacks
/** Unbind all bound image asynchronous load callbacks.
* @since v3.1
*/
virtual void unbindAllImageAsync();
@ -134,59 +138,61 @@ public:
/** Returns a Texture2D object given an Image.
* If the image was not previously loaded, it will create a new Texture2D object and it will return it.
* Otherwise it will return a reference of a previously loaded image.
* The "key" parameter will be used as the "key" for the cache.
* @param key The "key" parameter will be used as the "key" for the cache.
* If "key" is nil, then a new texture will be created each time.
*/
Texture2D* addImage(Image *image, const std::string &key);
CC_DEPRECATED_ATTRIBUTE Texture2D* addUIImage(Image *image, const std::string& key) { return addImage(image,key); }
/** Returns an already created texture. Returns nil if the texture doesn't exist.
@param key It's the related/absolute path of the file image.
@since v0.99.5
*/
Texture2D* getTextureForKey(const std::string& key) const;
CC_DEPRECATED_ATTRIBUTE Texture2D* textureForKey(const std::string& key) const { return getTextureForKey(key); }
/** Reload texture from the image file
/** Reload texture from the image file.
* If the file image hasn't loaded before, load it.
* Otherwise the texture will be reloaded from the file image.
* The "filenName" parameter is the related/absolute path of the file image.
* Return true if the reloading is succeed, otherwise return false.
* @param fileName It's the related/absolute path of the file image.
* @return True if the reloading is succeed, otherwise return false.
*/
bool reloadTexture(const std::string& fileName);
/** Purges the dictionary of loaded textures.
* Call this method if you receive the "Memory Warning"
* In the short term: it will free some resources preventing your app from being killed
* In the medium term: it will allocate more resources
* In the long term: it will be the same
* Call this method if you receive the "Memory Warning".
* In the short term: it will free some resources preventing your app from being killed.
* In the medium term: it will allocate more resources.
* In the long term: it will be the same.
*/
void removeAllTextures();
/** Removes unused textures
* Textures that have a retain count of 1 will be deleted
* It is convenient to call this method after when starting a new Scene
/** Removes unused textures.
* Textures that have a retain count of 1 will be deleted.
* It is convenient to call this method after when starting a new Scene.
* @since v0.8
*/
void removeUnusedTextures();
/** Deletes a texture from the cache given a texture
/** Deletes a texture from the cache given a texture.
*/
void removeTexture(Texture2D* texture);
/** Deletes a texture from the cache given a its key name
/** Deletes a texture from the cache given a its key name.
@param key It's the related/absolute path of the file image.
@since v0.99.4
*/
void removeTextureForKey(const std::string &key);
/** Output to CCLOG the current contents of this TextureCache
* This will attempt to calculate the size of each texture, and the total texture memory in use
/** Output to CCLOG the current contents of this TextureCache.
* This will attempt to calculate the size of each texture, and the total texture memory in use.
*
* @since v1.0
*/
std::string getCachedTextureInfo() const;
//wait for texture cahe to quit befor destroy instance
//called by director, please do not called outside
//Wait for texture cahe to quit befor destroy instance.
/**Called by director, please do not called outside.*/
void waitForQuit();
private: