Texture

Enums

enum sfTextureCoordinateType

Types of texture coordinates that can be used for rendering.

Values:

enumerator sfTextureNormalized

sfTexture coordinates in range [0 .. 1].

enumerator sfTexturePixels

sfTexture coordinates in range [0 .. size].

Functions

sfTexture *sfTexture_create(unsigned int width, unsigned int height)

Create a new texture.

Parameters:

• width – Texture width

• height – Texture height

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createFromFile(const char *filename, const sfIntRect *area)

Create a new texture from a file.

Parameters:

• filename – Path of the image file to load

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createSrgbFromFile(const char *filename, const sfIntRect *area)

Create a new sRGB-enabled texture from a file.

When providing texture data from an image file or memory, it can either be stored in a linear color space or an sRGB color space. Most digital images account for gamma correction already, so they would need to be “uncorrected” back to linear color space before being processed by the hardware. The hardware can automatically convert it from the sRGB color space to a linear color space when it gets sampled. When the rendered image gets output to the final framebuffer, it gets converted back to sRGB.

This load option is only useful in conjunction with an sRGB capable framebuffer. This can be requested during window creation.

Parameters:

• filename – Path of the image file to load

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createFromMemory(const void *data, size_t sizeInBytes, const sfIntRect *area)

Create a new texture from a file in memory.

Parameters:

• data – Pointer to the file data in memory

• sizeInBytes – Size of the data to load, in bytes

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createSrgbFromMemory(const void *data, size_t sizeInBytes, const sfIntRect *area)

Create a new sRGB-enabled texture from a file in memory.

Parameters:

• data – Pointer to the file data in memory

• sizeInBytes – Size of the data to load, in bytes

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createFromStream(sfInputStream *stream, const sfIntRect *area)

Create a new texture from a custom stream.

Parameters:

• stream – Source stream to read from

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createSrgbFromStream(sfInputStream *stream, const sfIntRect *area)

Create a new sRGB-enabled texture from a custom stream.

Parameters:

• stream – Source stream to read from

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createFromImage(const sfImage *image, const sfIntRect *area)

Create a new texture from an image.

Parameters:

• image – Image to upload to the texture

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_createSrgbFromImage(const sfImage *image, const sfIntRect *area)

Create a new sRGB-enabled texture from an image.

Parameters:

• image – Image to upload to the texture

• area – Area of the source image to load (NULL to load the entire image)

Returns:

A new sfTexture object, or NULL if it failed

sfTexture *sfTexture_copy(const sfTexture *texture)

Copy an existing texture.

Parameters:

• texture – Texture to copy

Returns:

Copied object

void sfTexture_destroy(sfTexture *texture)

Destroy an existing texture.

Parameters:

• texture – Texture to delete

sfVector2u sfTexture_getSize(const sfTexture *texture)

Return the size of the texture.

Parameters:

• texture – Texture to read

Returns:

Size in pixels

sfImage *sfTexture_copyToImage(const sfTexture *texture)

Copy a texture’s pixels to an image.

Parameters:

• texture – Texture to copy

Returns:

Image containing the texture’s pixels

void sfTexture_updateFromPixels(sfTexture *texture, const sfUint8 *pixels, unsigned int width, unsigned int height, unsigned int x, unsigned int y)

Update a texture from an array of pixels.

Parameters:

• texture – Texture to update

• 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 sfTexture_updateFromTexture(sfTexture *destination, const sfTexture *source, unsigned int x, unsigned int y)

Update a part of this texture from another texture.

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

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

Parameters:

• destination – Destination texture to copy source texture to

• source – Source texture to copy to destination texture

• x – X offset in this texture where to copy the source texture

• y – Y offset in this texture where to copy the source texture

void sfTexture_updateFromImage(sfTexture *texture, const sfImage *image, unsigned int x, unsigned int y)

Update a texture from an image.

Parameters:

• texture – Texture to update

• image – Image to copy to the texture

• 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 sfTexture_updateFromWindow(sfTexture *texture, const sfWindow *window, unsigned int x, unsigned int y)

Update a texture from the contents of a window.

Parameters:

• texture – Texture to update

• window – Window to copy to the texture

• 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 sfTexture_updateFromRenderWindow(sfTexture *texture, const sfRenderWindow *renderWindow, unsigned int x, unsigned int y)

Update a texture from the contents of a render-window.

Parameters:

• texture – Texture to update

• renderWindow – Render-window to copy to the texture

• 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 sfTexture_setSmooth(sfTexture *texture, sfBool smooth)

Enable or disable the smooth filter on a texture.

Parameters:

• texture – The texture object

• smooth – sfTrue to enable smoothing, sfFalse to disable it

sfBool sfTexture_isSmooth(const sfTexture *texture)

Tell whether the smooth filter is enabled or not for a texture.

Parameters:

• texture – The texture object

Returns:

sfTrue if smoothing is enabled, sfFalse if it is disabled

sfBool sfTexture_isSrgb(const sfTexture *texture)

Tell whether the texture source is converted from sRGB or not.

See also

sfTexture_setSrgb

Returns:

True if the texture source is converted from sRGB, false if not

void sfTexture_setRepeated(sfTexture *texture, sfBool repeated)

Enable or disable repeating for a texture.

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:

• texture – The texture object

• repeated – True to repeat the texture, false to disable repeating

sfBool sfTexture_isRepeated(const sfTexture *texture)

Tell whether a texture is repeated or not.

Parameters:

• texture – The texture object

Returns:

sfTrue if repeat mode is enabled, sfFalse if it is disabled

sfBool sfTexture_generateMipmap(sfTexture *texture)

Generate a mipmap using the current texture data.

Mipmaps are pre-computed chains of optimized textures. Each level of texture in a mipmap is generated by halving each of the previous level’s dimensions. This is done until the final level has the size of 1x1. The textures generated in this process may make use of more advanced filters which might improve the visual quality of textures when they are applied to objects much smaller than they are. This is known as minification. Because fewer texels (texture elements) have to be sampled from when heavily minified, usage of mipmaps can also improve rendering performance in certain scenarios.

Mipmap generation relies on the necessary OpenGL extension being available. If it is unavailable or generation fails due to another reason, this function will return false. Mipmap data is only valid from the time it is generated until the next time the base level image is modified, at which point this function will have to be called again to regenerate it.

Returns:

sfTrue if mipmap generation was successful, sfFalse if unsuccessful

void sfTexture_swap(sfTexture *left, sfTexture *right)

Swap the contents of a texture with those of another.

Parameters:

• left – Instance to swap from

• right – Instance to swap with

unsigned int sfTexture_getNativeHandle(const sfTexture *texture)

Get the underlying OpenGL handle of the texture.

You shouldn’t need to use this function, unless you have very specific stuff to implement that SFML doesn’t support, or implement a temporary workaround until a bug is fixed.

Parameters:

• texture – The texture object

Returns:

OpenGL handle of the texture or 0 if not yet created

void sfTexture_bind(const sfTexture *texture, sfTextureCoordinateType type)

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 sfTexture with OpenGL code.

sfTexture *t1, *t2;
...
sfTexture_bind(t1);
// draw OpenGL stuff that use t1...
sfTexture_bind(t2);
// draw OpenGL stuff that use t2...
sfTexture_bind(NULL);
// draw OpenGL stuff that use no texture...

Parameters:

• texture – Pointer to the texture to bind, can be null to use no texture

unsigned int sfTexture_getMaximumSize()

Get the maximum texture size allowed.

Returns:

Maximum size allowed for textures, in pixels