sf::Texture Class Reference
[Graphics module]

Image living on the graphics card that can be used for drawing. More...

#include <Texture.hpp>

Inheritance diagram for sf::Texture:
sf::Resource< Texture > sf::GlResource

List of all members.

Public Member Functions

 Texture ()
 Default constructor.
 Texture (const Texture &copy)
 Copy constructor.
 ~Texture ()
 Destructor.
bool Create (unsigned int width, unsigned int height)
 Create the texture.
bool LoadFromFile (const std::string &filename, const IntRect &area=IntRect())
 Load the texture from a file on disk.
bool LoadFromMemory (const void *data, std::size_t size, const IntRect &area=IntRect())
 Load the texture from a file in memory.
bool LoadFromStream (sf::InputStream &stream, const IntRect &area=IntRect())
 Load the texture from a file in memory.
bool LoadFromImage (const Image &image, const IntRect &area=IntRect())
 Load the texture from an image.
unsigned int GetWidth () const
 Return the width of the texture.
unsigned int GetHeight () const
 Return the height of the texture.
Image CopyToImage () const
 Copy the texture pixels to an image.
void Update (const Uint8 *pixels)
 Update the whole texture from an array of pixels.
void Update (const Uint8 *pixels, unsigned int width, unsigned int height, unsigned int x, unsigned int y)
 Update a part of the texture from an array of pixels.
void Update (const Image &image)
 Update the texture from an image.
void Update (const Image &image, unsigned int x, unsigned int y)
 Update a part of the texture from an image.
void Update (const Window &window)
 Update the texture from the contents of a window.
void Update (const Window &window, unsigned int x, unsigned int y)
 Update a part of the texture from the contents of a window.
void Bind () const
 Activate the texture for rendering.
void SetSmooth (bool smooth)
 Enable or disable the smooth filter.
bool IsSmooth () const
 Tell whether the smooth filter is enabled or not.
FloatRect GetTexCoords (const IntRect &rectangle) const
 Convert a rectangle of pixels into texture coordinates.
Textureoperator= (const Texture &right)
 Overload of assignment operator.

Static Public Member Functions

static unsigned int GetMaximumSize ()
 Get the maximum texture size allowed.

Static Private Member Functions

static void EnsureGlContext ()

Friends

class Renderer
class RenderTexture

Detailed Description

Image living on the graphics card that can be used for drawing.

sf::Texture stores pixels that can be drawn, with a sprite for example.

A texture lives in the graphics card memory, therefore it is very fast to draw a texture to a render target, or copy a render target to a texture (the graphics card can access both directly).

Being stored in the graphics card memory has some drawbacks. A texture cannot be manipulated as freely as a sf::Image, you need to prepare the pixels first and then upload them to the texture in a single operation (see Texture::Update).

sf::Texture makes it easy to convert from/to sf::Image, but keep in mind that these calls require transfers between the graphics card and the central memory, therefore they are slow operations.

A texture can be loaded from an image, but also directly from a file/memory/stream. The necessary shortcuts are defined so that you don't need an image first for the most common cases. However, if you want to perform some modifications on the pixels before creating the final texture, you can load your file to a sf::Image, do whatever you need with the pixels, and then call Texture::LoadFromImage.

Since they live in the graphics card memory, the pixels of a texture cannot be accessed without a slow copy first. And they cannot be accessed individually. Therefore, if you need to read the texture's pixels (like for pixel-perfect collisions), it is recommended to store the collision information separately, for example in an array of booleans.

Like sf::Image, sf::Texture can handle a unique internal representation of pixels, which is RGBA 32 bits. This means that a pixel must be composed of 8 bits red, green, blue and alpha channels -- just like a sf::Color.

Usage example:

 // This example shows the most common use of sf::Texture:
 // drawing a sprite

 // Load a texture from a file
 sf::Texture texture;
 if (!texture.LoadFromFile("texture.png"))
     return -1;

 // Assign it to a sprite
 sf::Sprite sprite;
 sprite.SetTexture(texture);

 // Draw the textured sprite
 window.Draw(sprite); // window is a sf::RenderWindow
 // This example shows another common use of sf::Texture:
 // streaming real-time data, like video frames

 // Create an empty texture
 sf::Texture texture;
 if (!texture.Create(640, 480))
     return -1;

 // Create a sprite that will display the texture
 sf::Sprite sprite(texture);

 while (...) // the main loop
 {
     ...

     // update the texture
     sf::Uint8* pixels = ...; // get a fresh chunk of pixels (the next frame of a movie, for example)
     texture.Update(pixels);

     // draw it
     window.Draw(sprite);

     ...
 }
See also:
sf::Sprite, sf::Image, sf::RenderTexture

Definition at line 47 of file Texture.hpp.


Constructor & Destructor Documentation

sf::Texture::Texture (  ) 

Default constructor.

Creates an empty texture.

sf::Texture::Texture ( const Texture copy  ) 

Copy constructor.

Parameters:
copy instance to copy
sf::Texture::~Texture (  ) 

Destructor.


Member Function Documentation

void sf::Texture::Bind (  )  const

Activate the texture for rendering.

This function is mainly used internally by the SFML render system. However it can be useful when using sf::Texture together with OpenGL code (this function is equivalent to glBindTexture).

Image sf::Texture::CopyToImage (  )  const

Copy the texture pixels to an image.

This function performs a slow operation that downloads the texture's pixels from the graphics card and copies them to a new image, potentially applying transformations to pixels if necessary (texture may be padded or flipped).

Returns:
Image containing the texture's pixels
See also:
LoadFromImage
bool sf::Texture::Create ( unsigned int  width,
unsigned int  height 
)

Create the texture.

If this function fails, the texture is left unchanged.

Parameters:
width Width of the texture
height Height of the texture
Returns:
True if creation was successful
unsigned int sf::Texture::GetHeight (  )  const

Return the height of the texture.

Returns:
Height in pixels
See also:
GetWidth
static unsigned int sf::Texture::GetMaximumSize (  )  [static]

Get the maximum texture size allowed.

This maximum size is defined by the graphics driver. You can expect a value of 512 pixels for low-end graphics card, and up to 8192 pixels or more for newer hardware.

Returns:
Maximum size allowed for textures, in pixels
FloatRect sf::Texture::GetTexCoords ( const IntRect rectangle  )  const

Convert a rectangle of pixels into texture coordinates.

This function is used by code that needs to map the texture to some OpenGL geometry. It converts the source rectangle, expressed in pixels, to float coordinates in the range [0, 1].

Parameters:
rectangle Rectangle to convert
Returns:
Texture coordinates corresponding to rectangle
unsigned int sf::Texture::GetWidth (  )  const

Return the width of the texture.

Returns:
Width in pixels
See also:
GetHeight
bool sf::Texture::IsSmooth (  )  const

Tell whether the smooth filter is enabled or not.

Returns:
True if smoothing is enabled, false if it is disabled
See also:
SetSmooth
bool sf::Texture::LoadFromFile ( const std::string &  filename,
const IntRect area = IntRect() 
)

Load the texture from a file on disk.

This function is a shortcut for the following code:

 sf::Image image;
 image.LoadFromFile(filename);
 texture.LoadFromImage(image, area);

The area argument can be used to load only a sub-rectangle of the whole image. If you want the entire image then leave the default value (which is an empty IntRect). If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and can be retrieved with the GetMaximumSize function.

If this function fails, the texture is left unchanged.

Parameters:
filename Path of the image file to load
area Area of the image to load
Returns:
True if loading was successful
See also:
LoadFromMemory, LoadFromStream, LoadFromImage
bool sf::Texture::LoadFromImage ( const Image image,
const IntRect area = IntRect() 
)

Load the texture from an image.

The area argument can be used to load only a sub-rectangle of the whole image. If you want the entire image then leave the default value (which is an empty IntRect). If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and can be retrieved with the GetMaximumSize function.

If this function fails, the texture is left unchanged.

Parameters:
image Image to load into the texture
area Area of the image to load
Returns:
True if loading was successful
See also:
LoadFromFile, LoadFromMemory
bool sf::Texture::LoadFromMemory ( const void *  data,
std::size_t  size,
const IntRect area = IntRect() 
)

Load the texture from a file in memory.

This function is a shortcut for the following code:

 sf::Image image;
 image.LoadFromMemory(data, size);
 texture.LoadFromImage(image, area);

The area argument can be used to load only a sub-rectangle of the whole image. If you want the entire image then leave the default value (which is an empty IntRect). If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and can be retrieved with the GetMaximumSize function.

If this function fails, the texture is left unchanged.

Parameters:
data Pointer to the file data in memory
size Size of the data to load, in bytes
area Area of the image to load
Returns:
True if loading was successful
See also:
LoadFromFile, LoadFromStream, LoadFromImage
bool sf::Texture::LoadFromStream ( sf::InputStream stream,
const IntRect area = IntRect() 
)

Load the texture from a file in memory.

This function is a shortcut for the following code:

 sf::Image image;
 image.LoadFromStream(stream);
 texture.LoadFromImage(image, area);

The area argument can be used to load only a sub-rectangle of the whole image. If you want the entire image then leave the default value (which is an empty IntRect). If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

The maximum size for a texture depends on the graphics driver and can be retrieved with the GetMaximumSize function.

If this function fails, the texture is left unchanged.

Parameters:
stream Source stream to read from
area Area of the image to load
Returns:
True if loading was successful
See also:
LoadFromFile, LoadFromMemory, LoadFromImage
Texture& sf::Texture::operator= ( const Texture right  ) 

Overload of assignment operator.

Parameters:
right Instance to assign
Returns:
Reference to self
void sf::Texture::SetSmooth ( bool  smooth  ) 

Enable or disable the smooth filter.

When the filter is activated, the texture appears smoother so that pixels are less noticeable. However if you want the texture to look exactly the same as its source file, you should leave it disabled. The smooth filter is disabled by default.

Parameters:
smooth True to enable smoothing, false to disable it
See also:
IsSmooth
void sf::Texture::Update ( const Window window,
unsigned int  x,
unsigned int  y 
)

Update a part of the texture from the contents of a window.

No additional check is performed on the size of the window, passing an invalid combination of window size and offset will lead to an undefined behaviour.

This function does nothing if either the texture or the window was not previously created.

Parameters:
window Window to copy to the texture
x X offset in the texture where to copy the source window
y Y offset in the texture where to copy the source window
void sf::Texture::Update ( const Window window  ) 

Update the texture from the contents of a window.

Although the source window can be smaller than the texture, this function is usually used for updating the whole texture. The other overload, which has (x, y) additional arguments, is more convenient for updating a sub-area of the texture.

No additional check is performed on the size of the window, passing a window bigger than the texture will lead to an undefined behaviour.

This function does nothing if either the texture or the window was not previously created.

Parameters:
window Window to copy to the texture
void sf::Texture::Update ( const Image image,
unsigned int  x,
unsigned int  y 
)

Update a part of the texture from an image.

No additional check is performed on the size of the image, passing an invalid combination of image size and offset will lead to an undefined behaviour.

This function does nothing if the texture was not previously created.

Parameters:
image Image to copy to the texture
x X offset in the texture where to copy the source image
y Y offset in the texture where to copy the source image
void sf::Texture::Update ( const Image image  ) 

Update the texture from an image.

Although the source image can be smaller than the texture, this function is usually used for updating the whole texture. The other overload, which has (x, y) additional arguments, is more convenient for updating a sub-area of the texture.

No additional check is performed on the size of the image, passing an image bigger than the texture will lead to an undefined behaviour.

This function does nothing if the texture was not previously created.

Parameters:
image Image to copy to the texture
void sf::Texture::Update ( const Uint8 *  pixels,
unsigned int  width,
unsigned int  height,
unsigned int  x,
unsigned int  y 
)

Update a part of the texture from an array of pixels.

The size of the pixels array must match the width and height arguments, and it must contain 32-bits RGBA pixels.

No additional check is performed on the size of the pixel array or the bounds of the area to update, passing invalid arguments will lead to an undefined behaviour.

This function does nothing if pixels is null or if the texture was not previously created.

Parameters:
pixels Array of pixels to copy to the texture
width Width of the pixel region contained in pixels
height Height of the pixel region contained in pixels
x X offset in the texture where to copy the source pixels
y Y offset in the texture where to copy the source pixels
void sf::Texture::Update ( const Uint8 *  pixels  ) 

Update the whole texture from an array of pixels.

The pixels array is assumed to have the same size as the area rectangle, and to contain 32-bits RGBA pixels.

No additional check is performed on the size of the pixel array, passing invalid arguments will lead to an undefined behaviour.

This function does nothing if pixels is null or if the texture was not previously created.

Parameters:
pixels Array of pixels to copy to the texture

The documentation for this class was generated from the following file: