# CCSprite Class Reference

Inherits from | CCNode : CCResponder : NSObject
Conforms to | CCBlendProtocol CCEffectProtocol CCShaderProtocol CCTextureProtocol
Declared in | CCSprite.h

## Overview

CCSprite is a 2D image ( http://en.wikipedia.org/wiki/Sprite_(computer_graphics) )

CCSprite can be created with an image, or with a sub-rectangle of an image.

The default anchorPoint in CCSprite is (0.5, 0.5).

## Tasks

### Other Methods

- `textureRect` property
- `textureRectRotated` property
- `spriteFrame` property
- `flipX` property
- `flipY` property
- `offsetPosition` property
- `normalMapSpriteFrame` property

### Creating a CCSprite Object

- `+ spriteWithImageNamed:`
- `+ spriteWithTexture:`
- `+ spriteWithTexture:rect:`
- `+ spriteWithSpriteFrame:`
- `+ spriteWithCGImage:key:`

### Initializing a CCSprite Object

- `– initWithImageNamed:`
- `– initWithTexture:`
- `– initWithTexture:rect:`
- `– initWithSpriteFrame:`
- `– initWithCGImage:key:`
- `+ emptySprite`
- `– initWithTexture:rect:rotated:`

### Textures Methods

- `– setTextureRect:`
- `– setTextureRect:rotated:untrimmedSize:`

### Accessing Transformations and Matrices

- `– nodeToTextureTransform`

## Properties

### flipX

Whether or not the sprite is flipped horizontally. It only flips the texture of the sprite, and not the texture of the sprite’s children. Also, flipping the texture doesn’t alter the anchorPoint. If you want to flip the anchorPoint too, and/or to flip the children too use: sprite.scaleX *= -1;

`@property (nonatomic, readwrite) BOOL flipX`

#### Declared In

`CCSprite.h`

### flipY

Whether or not the sprite is flipped vertically. It only flips the texture of the sprite, and not the texture of the sprite’s children. Also, flipping the texture doesn’t alter the anchorPoint. If you want to flip the anchorPoint too, and/or to flip the children too use: sprite.scaleY *= -1;

`@property (nonatomic, readwrite) BOOL flipY`

#### Declared In

`CCSprite.h`

### normalMapSpriteFrame

The current normal map spriteFrame.

`@property (nonatomic, strong) CCSpriteFrame *normalMapSpriteFrame`

#### Declared In

`CCSprite.h`

### offsetPosition

The offset position in points of the sprite in points. Calculated automatically by sprite sheet editors.

`@property (nonatomic, readonly) CGPoint offsetPosition`

#### Declared In

`CCSprite.h`

### spriteFrame

The currently displayed spriteFrame.

`@property (nonatomic, strong) CCSpriteFrame *spriteFrame`

#### Declared In

`CCSprite.h`

### textureRect

Returns the texture rect of the CCSprite in points.

`@property (nonatomic, readonly) CGRect textureRect`

#### Declared In

`CCSprite.h`

### textureRectRotated

Returns whether or not the texture rectangle is rotated.

`@property (nonatomic, readonly) BOOL textureRectRotated`

#### Declared In

`CCSprite.h`

## Class Methods

### emptySprite

Creates a non rendered sprite, the primary use of this type of sprite would be for adding control sprites for more complex animations.

`+ (id)emptySprite`

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### spriteWithCGImage:key:

Creates an sprite with a CGImageRef and a key. The key is used by the CCTextureCache to know if a texture was already created with this CGImage. For example, a valid key is: @“_spriteframe_01”. If key is nil, then a new texture will be created each time by the CCTextureCache.

`+ (id)spriteWithCGImage:(CGImageRef)image key:(NSString *)key`

#### Parameters

image

  Image ref.

key

  Key description.

#### Return Value

The CCSprite Object.

#### Declared In

`CCSprite.h`

### spriteWithImageNamed:

Creates a sprite with the name of an image. The name can be either a name in a sprite sheet or the name of a file.

`+ (id)spriteWithImageNamed:(NSString *)imageName`

#### Parameters

imageName

  name of the image to load.

#### Return Value

The CCSprite Object.

#### Declared In

`CCSprite.h`

### spriteWithSpriteFrame:

Creates an sprite from a sprite frame.

`+ (id)spriteWithSpriteFrame:(CCSpriteFrame *)spriteFrame`

#### Parameters

spriteFrame

  Sprite frame to use.

#### Return Value

The CCSprite Object.

#### Declared In

`CCSprite.h`

### spriteWithTexture:

Creates an sprite with a texture. The rect used will be the size of the texture. The offset will be (0,0).

`+ (id)spriteWithTexture:(CCTexture *)texture`

#### Parameters

texture

  Texture to use.

#### Return Value

The CCSprite Object.

#### Declared In

`CCSprite.h`

### spriteWithTexture:rect:

Creates an sprite with a texture. The offset will be (0,0).

`+ (id)spriteWithTexture:(CCTexture *)texture rect:(CGRect)rect`

#### Parameters

texture

  Texture to use.

rect

  Rect to use.

#### Return Value

The CCSprite Object.

#### Declared In

`CCSprite.h`

## Instance Methods

### initWithCGImage:key:

Initializes an sprite with a CGImageRef and a key. The key is used by the CCTextureCache to know if a texture was already created with this CGImage. For example, a valid key is: @“_spriteframe_01”. If key is nil, then a new texture will be created each time by the CCTextureCache.

`- (id)initWithCGImage:(CGImageRef)image key:(NSString *)key`

#### Parameters

image

  Image ref.

key

  Key description.

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### initWithImageNamed:

Initializes a sprite with the name of an image. The name can be either a name in a sprite sheet or the name of a file.

`- (id)initWithImageNamed:(NSString *)imageName`

#### Parameters

imageName

  name of the image to load.

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### initWithSpriteFrame:

Initializes an sprite with an sprite frame.

`- (id)initWithSpriteFrame:(CCSpriteFrame *)spriteFrame`

#### Parameters

spriteFrame

  Sprite frame to use.

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### initWithTexture:

Initializes an sprite with a texture. The rect used will be the size of the texture. The offset will be (0,0).

`- (id)initWithTexture:(CCTexture *)texture`

#### Parameters

texture

  The texture to use.

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### initWithTexture:rect:

Initializes an sprite with a texture and a rect in points (unrotated) The offset will be (0,0).

`- (id)initWithTexture:(CCTexture *)texture rect:(CGRect)rect`

#### Parameters

texture

  The texture to use.

rect

  The rect to use.

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### initWithTexture:rect:rotated:

Designated initializer. Initializes an sprite with a texture and a rect in points, optionally rotated. The offset will be (0,0). IMPORTANT: This is the designated initializer.

`- (id)initWithTexture:(CCTexture *)texture rect:(CGRect)rect rotated:(BOOL)rotated`

#### Parameters

texture

  The texture to use.

rect

  The rect to use.

rotated

  YES if texture is rotated.

#### Return Value

A newly initialized CCSprite object.

#### Declared In

`CCSprite.h`

### nodeToTextureTransform

Returns the matrix that transforms the sprite’s (local) space coordinates into the sprite’s texture space coordinates.

`- (CGAffineTransform)nodeToTextureTransform`

#### Declared In

`CCSprite.h`

### setTextureRect:

Set the texture rect of the CCSprite in points. It will call setTextureRect:rotated:untrimmedSize with rotated = NO, and utrimmedSize = rect.size.

`- (void)setTextureRect:(CGRect)rect`

#### Parameters

rect

  Rect to use.

#### Declared In

`CCSprite.h`

### setTextureRect:rotated:untrimmedSize:

Set the texture rect, rectRotated and untrimmed size of the CCSprite in points. It will update the texture coordinates and the vertex rectangle.

`- (void)setTextureRect:(CGRect)rect rotated:(BOOL)rotated untrimmedSize:(CGSize)size`

#### Parameters

rect

  Rect to use.

rotated

  YES if texture is rotated.

size

  Untrimmed size.

#### Declared In

`CCSprite.h`