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

#include <Texture.hpp>

Inheritance diagram for sf::Texture:

Public Types
enum	CoordinateType { Normalized, Pixels }
	Types of texture coordinates that can be used for rendering. More...

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 custom stream.

bool	loadFromImage (const Image &image, const IntRect &area=IntRect())
	Load the texture from an image.

Vector2u	getSize () const
	Return the size 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	setSmooth (bool smooth)
	Enable or disable the smooth filter.

bool	isSmooth () const
	Tell whether the smooth filter is enabled or not.

void	setRepeated (bool repeated)
	Enable or disable repeating.

bool	isRepeated () const
	Tell whether the texture is repeated or not.

Texture &	operator= (const Texture &right)
	Overload of assignment operator.

Static Public Member Functions
static void	bind (const Texture *texture, CoordinateType coordinateType=Normalized)
	Bind a texture for rendering.

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

Static Private Member Functions
static void	ensureGlContext ()
	Make sure that a valid OpenGL context exists in the current thread.

Friends
class	RenderTexture

class	RenderTarget

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);

// 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);
    ...
}

Like sf::Shader that can be used as a raw OpenGL shader, sf::Texture can also be used directly as a raw texture for custom OpenGL geometry.

sf::Texture::bind(&texture);
... render OpenGL geometry ...
sf::Texture::bind(NULL);

See Also: sf::Sprite, sf::Image, sf::RenderTexture

Definition at line 47 of file Texture.hpp.

Member Enumeration Documentation

enum sf::Texture::CoordinateType

Types of texture coordinates that can be used for rendering.

Enumerator:

Normalized	Texture coordinates in range [0 .. 1].
Pixels	Texture coordinates in range [0 .. size].

Definition at line 55 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

static void sf::Texture::bind	(	const Texture *	texture,
		CoordinateType	coordinateType = `Normalized`
	)

static

Bind a texture for rendering.

This function is not part of the graphics API, it mustn't be used when drawing SFML entities. It must be used only if you mix sf::Texture with OpenGL code.

sf::Texture t1, t2;
...
sf::Texture::bind(&t1);
// draw OpenGL stuff that use t1...
sf::Texture::bind(&t2);
// draw OpenGL stuff that use t2...
sf::Texture::bind(NULL);
// draw OpenGL stuff that use no texture...

The coordinateType argument controls how texture coordinates will be interpreted. If Normalized (the default), they must be in range [0 .. 1], which is the default way of handling texture coordinates with OpenGL. If Pixels, they must be given in pixels (range [0 .. size]). This mode is used internally by the graphics classes of SFML, it makes the definition of texture coordinates more intuitive for the high-level API, users don't need to compute normalized values.

Parameters

texture	Pointer to the texture to bind, can be null to use no texture
coordinateType	Type of texture coordinates to use

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

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

Vector2u sf::Texture::getSize ( ) const

Return the size of the texture.

Returns: Size in pixels

bool sf::Texture::isRepeated ( ) const

Tell whether the texture is repeated or not.

Returns: True if repeat mode is enabled, false if it is disabled

See Also: setRepeated

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 custom stream.

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::setRepeated ( bool repeated )

Enable or disable repeating.

Repeating is involved when using texture coordinates outside the texture rectangle [0, 0, width, height]. In this case, if repeat mode is enabled, the whole texture will be repeated as many times as needed to reach the coordinate (for example, if the X texture coordinate is 3 * width, the texture will be repeated 3 times). If repeat mode is disabled, the "extra space" will instead be filled with border pixels. Warning: on very old graphics cards, white pixels may appear when the texture is repeated. With such cards, repeat mode can be used reliably only if the texture has power-of-two dimensions (such as 256x128). Repeating is disabled by default.

Parameters

repeated True to repeat the texture, false to disable repeating

See Also: isRepeated

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 Uint8 * pixels )

Update the whole texture from an array of pixels.

The pixel 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

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 pixel 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 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 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 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 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

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

Texture.hpp

Documentation of SFML 2.1

Public Types

Public Member Functions

Static Public Member Functions

Static Private Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation