Functions
Texture.h File Reference
#include <SFML/Graphics/Export.h>
#include <SFML/Graphics/Rect.h>
#include <SFML/Graphics/Types.h>
#include <SFML/Window/Types.h>
#include <SFML/System/InputStream.h>
#include <SFML/System/Vector2.h>
#include <stddef.h>

Go to the source code of this file.

Functions

CSFML_GRAPHICS_API sfTexturesfTexture_create (unsigned int width, unsigned int height)
 Create a new texture. More...
 
CSFML_GRAPHICS_API sfTexturesfTexture_createFromFile (const char *filename, const sfIntRect *area)
 Create a new texture from a file. More...
 
CSFML_GRAPHICS_API sfTexturesfTexture_createFromMemory (const void *data, size_t sizeInBytes, const sfIntRect *area)
 Create a new texture from a file in memory. More...
 
CSFML_GRAPHICS_API sfTexturesfTexture_createFromStream (sfInputStream *stream, const sfIntRect *area)
 Create a new texture from a custom stream. More...
 
CSFML_GRAPHICS_API sfTexturesfTexture_createFromImage (const sfImage *image, const sfIntRect *area)
 Create a new texture from an image. More...
 
CSFML_GRAPHICS_API sfTexturesfTexture_copy (const sfTexture *texture)
 Copy an existing texture. More...
 
CSFML_GRAPHICS_API void sfTexture_destroy (sfTexture *texture)
 Destroy an existing texture. More...
 
CSFML_GRAPHICS_API sfVector2u sfTexture_getSize (const sfTexture *texture)
 Return the size of the texture. More...
 
CSFML_GRAPHICS_API sfImagesfTexture_copyToImage (const sfTexture *texture)
 Copy a texture's pixels to an image. More...
 
CSFML_GRAPHICS_API 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. More...
 
CSFML_GRAPHICS_API void sfTexture_updateFromImage (sfTexture *texture, const sfImage *image, unsigned int x, unsigned int y)
 Update a texture from an image. More...
 
CSFML_GRAPHICS_API void sfTexture_updateFromWindow (sfTexture *texture, const sfWindow *window, unsigned int x, unsigned int y)
 Update a texture from the contents of a window. More...
 
CSFML_GRAPHICS_API void sfTexture_updateFromRenderWindow (sfTexture *texture, const sfRenderWindow *renderWindow, unsigned int x, unsigned int y)
 Update a texture from the contents of a render-window. More...
 
CSFML_GRAPHICS_API void sfTexture_setSmooth (sfTexture *texture, sfBool smooth)
 Enable or disable the smooth filter on a texture. More...
 
CSFML_GRAPHICS_API sfBool sfTexture_isSmooth (const sfTexture *texture)
 Tell whether the smooth filter is enabled or not for a texture. More...
 
CSFML_GRAPHICS_API void sfTexture_setSrgb (sfTexture *texture, sfBool sRgb)
 Enable or disable conversion from sRGB. More...
 
CSFML_GRAPHICS_API sfBool sfTexture_isSrgb (const sfTexture *texture)
 Tell whether the texture source is converted from sRGB or not. More...
 
CSFML_GRAPHICS_API void sfTexture_setRepeated (sfTexture *texture, sfBool repeated)
 Enable or disable repeating for a texture. More...
 
CSFML_GRAPHICS_API sfBool sfTexture_isRepeated (const sfTexture *texture)
 Tell whether a texture is repeated or not. More...
 
CSFML_GRAPHICS_API sfBool sfTexture_generateMipmap (sfTexture *texture)
 Generate a mipmap using the current texture data. More...
 
CSFML_GRAPHICS_API unsigned int sfTexture_getNativeHandle (const sfTexture *texture)
 Get the underlying OpenGL handle of the texture. More...
 
CSFML_GRAPHICS_API void sfTexture_bind (const sfTexture *texture)
 Bind a texture for rendering. More...
 
CSFML_GRAPHICS_API unsigned int sfTexture_getMaximumSize ()
 Get the maximum texture size allowed. More...
 

Function Documentation

◆ sfTexture_bind()

CSFML_GRAPHICS_API void sfTexture_bind ( const sfTexture texture)

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...
// draw OpenGL stuff that use t2...
// draw OpenGL stuff that use no texture...
Parameters
texturePointer to the texture to bind, can be null to use no texture

◆ sfTexture_copy()

CSFML_GRAPHICS_API sfTexture* sfTexture_copy ( const sfTexture texture)

Copy an existing texture.

Parameters
textureTexture to copy
Returns
Copied object

◆ sfTexture_copyToImage()

CSFML_GRAPHICS_API sfImage* sfTexture_copyToImage ( const sfTexture texture)

Copy a texture's pixels to an image.

Parameters
textureTexture to copy
Returns
Image containing the texture's pixels

◆ sfTexture_create()

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

Create a new texture.

Parameters
widthTexture width
heightTexture height
Returns
A new sfTexture object, or NULL if it failed

◆ sfTexture_createFromFile()

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

Create a new texture from a file.

Parameters
filenamePath of the image file to load
areaArea of the source image to load (NULL to load the entire image)
Returns
A new sfTexture object, or NULL if it failed

◆ sfTexture_createFromImage()

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

Create a new texture from an image.

Parameters
imageImage to upload to the texture
areaArea of the source image to load (NULL to load the entire image)
Returns
A new sfTexture object, or NULL if it failed

◆ sfTexture_createFromMemory()

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

Create a new texture from a file in memory.

Parameters
dataPointer to the file data in memory
sizeInBytesSize of the data to load, in bytes
areaArea of the source image to load (NULL to load the entire image)
Returns
A new sfTexture object, or NULL if it failed

◆ sfTexture_createFromStream()

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

Create a new texture from a custom stream.

Parameters
streamSource stream to read from
areaArea of the source image to load (NULL to load the entire image)
Returns
A new sfTexture object, or NULL if it failed

◆ sfTexture_destroy()

CSFML_GRAPHICS_API void sfTexture_destroy ( sfTexture texture)

Destroy an existing texture.

Parameters
textureTexture to delete

◆ sfTexture_generateMipmap()

CSFML_GRAPHICS_API 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

◆ sfTexture_getMaximumSize()

CSFML_GRAPHICS_API unsigned int sfTexture_getMaximumSize ( )

Get the maximum texture size allowed.

Returns
Maximum size allowed for textures, in pixels

◆ sfTexture_getNativeHandle()

CSFML_GRAPHICS_API 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
textureThe texture object
Returns
OpenGL handle of the texture or 0 if not yet created

◆ sfTexture_getSize()

CSFML_GRAPHICS_API sfVector2u sfTexture_getSize ( const sfTexture texture)

Return the size of the texture.

Parameters
textureTexture to read
Returns
Size in pixels

◆ sfTexture_isRepeated()

CSFML_GRAPHICS_API sfBool sfTexture_isRepeated ( const sfTexture texture)

Tell whether a texture is repeated or not.

Parameters
textureThe texture object
Returns
sfTrue if repeat mode is enabled, sfFalse if it is disabled

◆ sfTexture_isSmooth()

CSFML_GRAPHICS_API sfBool sfTexture_isSmooth ( const sfTexture texture)

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

Parameters
textureThe texture object
Returns
sfTrue if smoothing is enabled, sfFalse if it is disabled

◆ sfTexture_isSrgb()

CSFML_GRAPHICS_API sfBool sfTexture_isSrgb ( const sfTexture texture)

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

Returns
True if the texture source is converted from sRGB, false if not
See also
sfTexture_setSrgb

◆ sfTexture_setRepeated()

CSFML_GRAPHICS_API 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
textureThe texture object
repeatedTrue to repeat the texture, false to disable repeating

◆ sfTexture_setSmooth()

CSFML_GRAPHICS_API void sfTexture_setSmooth ( sfTexture texture,
sfBool  smooth 
)

Enable or disable the smooth filter on a texture.

Parameters
textureThe texture object
smoothsfTrue to enable smoothing, sfFalse to disable it

◆ sfTexture_setSrgb()

CSFML_GRAPHICS_API void sfTexture_setSrgb ( sfTexture texture,
sfBool  sRgb 
)

Enable or disable conversion from sRGB.

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.

After enabling or disabling sRGB conversion, make sure to reload the texture data in order for the setting to take effect.

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

Parameters
sRgbTrue to enable sRGB conversion, false to disable it
See also
sfTexture_isSrgb

◆ sfTexture_updateFromImage()

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

Update a texture from an image.

Parameters
textureTexture to update
imageImage to copy to the texture
xX offset in the texture where to copy the source pixels
yY offset in the texture where to copy the source pixels

◆ sfTexture_updateFromPixels()

CSFML_GRAPHICS_API 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
textureTexture to update
pixelsArray of pixels to copy to the texture
widthWidth of the pixel region contained in pixels
heightHeight of the pixel region contained in pixels
xX offset in the texture where to copy the source pixels
yY offset in the texture where to copy the source pixels

◆ sfTexture_updateFromRenderWindow()

CSFML_GRAPHICS_API 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
textureTexture to update
renderWindowRender-window to copy to the texture
xX offset in the texture where to copy the source pixels
yY offset in the texture where to copy the source pixels

◆ sfTexture_updateFromWindow()

CSFML_GRAPHICS_API void sfTexture_updateFromWindow ( sfTexture texture,
const sfWindow window,
unsigned int  x,
unsigned int  y 
)

Update a texture from the contents of a window.

Parameters
textureTexture to update
windowWindow to copy to the texture
xX offset in the texture where to copy the source pixels
yY offset in the texture where to copy the source pixels