Graphics

PrimitiveType

class sfml.graphics.PrimitiveType

Empty class that defines some constants. The are the types of primitives that an VertexArray can render.

POINTS and LINES have no area, therefore their thickness will always be 1 pixel, regardless of the current transform and view.

POINTS

List of individual points.

LINES

List of individual lines.

LINES_STRIP

List of connected lines, a point uses the previous point to form a line.

TRIANGLES

List of individual triangles.

TRIANGLES_STRIP

List of connected triangles, a point uses the two previous points to form a triangle.

TRIANGLES_FAN

List of connected triangles, a point uses the common center and the previous point to form a triangle.

QUADS

List of individual quads.

Rectangle

class sfml.graphics.Rectangle

Utility class for manipulating 2D axis aligned rectangles.

A rectangle is defined by its top-left corner and its size.

It is a very simple class defined for convenience, so its member variables (left, top, width and height) are public and can be accessed directly via attributes, just like Vector2.

Unlike SFML, Rectangle does define functions to emulate the properties that are not directly members (such as right, bottom, center, etc.).

Rectangle uses the usual rules for its boundaries:

  • The left and top edges are included in the rectangle’s area
  • The right (left + width) and bottom (top + height) edges are excluded from the rectangle’s area

This means that (0, 0, 1, 1) and (1, 1, 1, 1) don’t intersect.

Usage example:

# define a rectangle, located at (0, 0) with a size of 20x5
r1 = sf.Rectangle(sf.Vector2(0, 0), sf.Vector2(20, 5))
# or r1 = sf.Rectangle((0, 0), (20, 5))

# define another rectangle, located at (4, 2) with a size of 18x10
position = sf.Vector2(4, 2)
size = sf.Vector2(18, 10)

r2 = sf.Rectangle(position, size)

# test intersections with the point (3, 1)
b1 = r1.contains(sf.Vector2(3, 1)) # True
b2 = r2.contains((3, 1)) # False

# test the intersection between r1 and r2
result = r1.intersects(r2) # True

# as there's an intersection, the result is not None but (4, 2, 16, 3)
assert result == sf.Rectangle((4, 2), (16, 3))
Rectangle(position=(0, 0), size=(0, 0))

Construct an sfml.graphics.Rectangle

position

Top-left coordinate of the rectangle.

size

Position of the rectangle.

left

Left coordinate of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.x

top

Top coordinate of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.y

width

Width of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.size.width

height

Height of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.height

center

The center of the rectangle.

right

The right coordinate of the rectangle.

bottom

The bottom coordinate of the rectangle.

contains(point)

Check if a point is inside the rectangle’s area.

Parameters:point (sfml.system.Vector2) – Point to test
Return type:bool
intersects(rectangle)

Check the intersection between two rectangles.

This overload returns the overlapped rectangle if an intersection is found.

Parameters:rectangle (sfml.graphics.Rectangle) – Rectangle to test
Returns:Rectangle filled with the intersection or None
Return type:sfml.graphics.Rectangle or None

Color

class sfml.graphics.Color

Utility class for manipulating RGBA colors.

Color is a simple color class composed of 4 components:

  • Red,
  • Green
  • Blue
  • Alpha (opacity)

Each component is a property, an unsigned integer in the range [0, 255]. Thus, colors can be constructed and manipulated very easily:

c1 = sf.Color(255, 0, 0) # red
c1.r = 0                 # make it black
c1.b = 128               # make it dark blue

The fourth component of colors, named “alpha”, represents the opacity of the color. A color with an alpha value of 255 will be fully opaque, while an alpha value of 0 will make a color fully transparent, whatever the value of the other components is.

The most common colors are already defined.

black       = sf.Color.BLACK
white       = sf.Color.WHITE
red         = sf.Color.RED
green       = sf.Color.GREEN
blue        = sf.Color.BLUE
yellow      = sf.Color.YELLOW
magenta     = sf.Color.MAGENTA
cyan        = sf.Color.CYAN
transparent = sf.Color.TRANSPARENT

Colors can also be added and modulated (multiplied) using the overloaded operators + and *.

Color([r=0[, g=0[, b=0[, a=255]]]])

Construct the color from its 4 RGBA components.

Parameters:
  • r (integer) – Red component (in the range [0, 255])
  • g (integer) – Green component (in the range [0, 255])
  • b (integer) – Blue component (in the range [0, 255])
  • a (integer) – Alpha (opacity) component (in the range [0, 255])
BLACK

Black predefined color.

WHITE

White predefined color.

RED

Red predefined color.

GREEN

Green predefined color.

BLUE

Blue predefined color.

YELLOW

Yellow predefined color.

MAGENTA

Magenta predefined color.

CYAN

Cyan predefined color.

TRANSPARENT

Transparent (black) predefined color.

r

Red component.

g

Green component.

b

Blue component.

a

Alpha (opacity) component.

Transform

class sfml.graphics.Transform

Define a 3x3 transform matrix.

A Transform specifies how to translate, rotate, scale, shear, project, whatever things.

In mathematical terms, it defines how to transform a coordinate system into another.

For example, if you apply a rotation transform to a sprite, the result will be a rotated sprite. And anything that is transformed by this rotation transform will be rotated the same way, according to its initial position.

Transforms are typically used for drawing. But they can also be used for any computation that requires to transform points between the local and global coordinate systems of an entity (like collision detection).

Usage example:

# define a translation transform
translation = sf.Transform()
translation.translate((20, 50))

# define a rotation transform
rotation = sf.Transform()
rotation.rotate(45)

# combine them
transform = translation * rotation

# use the result to transform stuff...
point = transform.transform_point((10, 20))
rectangle = transform.transform_rectangle(sf.Rectangle((0, 0), (10, 100)))
classmethod from_values(a00, a01, a02, a10, a11, a12, a20, a21, a22)

Construct a transform from a 3x3 matrix

Parameters:
  • a00 (float) – Element (0, 0) of the matrix
  • a01 (float) – Element (0, 1) of the matrix
  • a02 (float) – Element (0, 2) of the matrix
  • a10 (float) – Element (1, 0) of the matrix
  • a11 (float) – Element (1, 1) of the matrix
  • a12 (float) – Element (1, 2) of the matrix
  • a20 (float) – Element (2, 0) of the matrix
  • a21 (float) – Element (2, 1) of the matrix
  • a22 (float) – Element (2, 2) of the matrix
Return type:

sfml.graphics.Transform
matrix

Return the transform as a 4x4 matrix.

This function returns a pointer to an array of 16 floats containing the transform elements as a 4x4 matrix, which is directly compatible with OpenGL functions.

Type:long
inverse

Return the inverse of the transform.

If the inverse cannot be computed, an identity transform is returned.

Type:sfml.graphics.Transform
transform_point(point)

Transform a 2D point.

Parameters:point (sfml.system.Vector2 or tuple) – Point to transform
Returns:Transformed point
Return type:sfml.system.Vector2
transform_rectangle(rectangle)

Transform a rectangle.

Since SFML doesn’t provide support for oriented rectangles, the result of this function is always an axis-aligned rectangle. Which means that if the transform contains a rotation, the bounding rectangle of the transformed rectangle is returned.

Parameters:rectangle (sfml.graphics.Rectangle or tuple) – Rectangle to transform
Returns:Transformed rectangle
Return type:sfml.graphics.Rectangle
combine(transform)

Combine the current transform with another one.

The result is a transform that is equivalent to applying this followed by transform. Mathematically, it is equivalent to a matrix multiplication.

This function returns a reference self, so that calls can be chained.

Parameters:transform (sfml.graphics.Rectangle) – Transform to combine with this transform
Returns:Return itself
Return type:sfml.graphics.Transform
translate(offset)

Combine the current transform with a translation.

This function returns a reference to self, so that calls can be chained.

transform = sf.Transform()
transform.translate(sf.Vector2(100, 200)).rotate(45)
Parameters:offset (sfml.system.Vector2 or tuple) – Translation offset to apply
Returns:Return itself
Return type:sfml.graphics.Transform
rotate(angle[, center])

Combine the current transform with a rotation.

The center of rotation is provided for convenience as a second argument, so that you can build rotations around arbitrary points more easily (and efficiently) than the usual translate(-center).rotate(angle).translate(center).

This function returns a reference to self, so that calls can be chained.

transform = sf.Transform()
transform.rotate(90, (8, 3)).translate((50, 20))
Parameters:
  • angle (float) – Rotation angle, in degrees
  • center (sfml.system.Vector2 or tuple) – Center of rotation
Returns:

Return itself
Return type:

sfml.graphics.Transform
scale(factor[, center])

Combine the current transform with a scaling.

The center of scaling is provided for convenience as a second argument, so that you can build scaling around arbitrary points more easily (and efficiently) than the usual translate(-center).scale(factors).translate(center).

This function returns a reference to self, so that calls can be chained.

transform = sf.Transform()
transform.scale((2, 1), (8, 3)).rotate(45)
Parameters:
Returns:

Return itself
Return type:

sfml.graphics.Transform

BlendMode

class sfml.graphics.BlendMode

BlendMode is a class that represents a blend mode. A blend mode determines how the colors of an object you draw are mixed with the colors that are already in the buffer.

The class is composed of 6 components, each of which has its own public member variable:

The source factor specifies how the pixel you are drawing contributes to the final color. The destination factor specifies how the pixel already drawn in the buffer contributes to the final color.

The color channels RGB (red, green, blue; simply referred to as color) and A (alpha; the transparency) can be treated separately. This separation can be useful for specific blend modes, but most often you won’t need it and will simply treat the color as a single unit.

The blend factors and equations correspond to their OpenGL equivalents. In general, the color of the resulting pixel is calculated according to the following formula src is the color of the source pixel, dst the color of the destination pixel, the other variables correspond to the public members, with the equations being + or - operators):

dst.rgb = colorSrcFactor * src.rgb (colorEquation) colorDstFactor * dst.rgb
dst.a   = alphaSrcFactor * src.a   (alphaEquation) alphaDstFactor * dst.a

All factors and colors are represented as floating point numbers between 0 and 1. Where necessary, the result is clamped to fit in that range.

The most common blending modes are defined as constants in the sf namespace:

sf.BLEND_ALPHA
sf.BLEND_ADD
sf.BLEND_MULTIPLY
sf.BLEND_NONE

In SFML, a blend mode can be specified every time you draw a Drawable object to a render target. It is part of the RenderStates compound that is passed to the member function draw().

Factor Description
ZERO (0, 0, 0, 0)
ONE (1, 1, 1, 1)
SRC_COLOR (src.r, src.g, src.b, src.a)
ONE_MINUS_SRC_COLOR (1, 1, 1, 1) - (src.r, src.g, src.b, src.a)
DST_COLOR (dst.r, dst.g, dst.b, dst.a)
ONE_MINUS_DST_COLOR (1, 1, 1, 1) - (dst.r, dst.g, dst.b, dst.a)
SRC_ALPHA (src.a, src.a, src.a, src.a)
ONE_MINUS_SRC_ALPHA (1, 1, 1, 1) - (src.a, src.a, src.a, src.a)
DST_ALPHA (dst.a, dst.a, dst.a, dst.a)
ONE_MINUS_DST_ALPHA (1, 1, 1, 1) - (dst.a, dst.a, dst.a, dst.a)
Equation Description
ADD Pixel = Src * SrcFactor + Dst * DstFactor
SUBTRACT Pixel = Src * SrcFactor - Dst * DstFactor
BlendMode(*args, **kwargs):

Construct the blend mode given the factors and equation.

Parameters:
  • color_source_factor (integer) – Specifies how to compute the source factor for the color channels.
  • color_destination_factor (integer) – Specifies how to compute the destination factor for the color channels.
  • color_blend_equation (integer) – Specifies how to combine the source and destination colors.
  • alpha_source_factor (integer) – Specifies how to compute the source factor.
  • alpha_destination_factor (integer) – Specifies how to compute the destination factor.
  • alpha_blend_equation (integer) – Specifies how to combine the source and destination alphas.
color_src_factor

Source blending factor for the color channels

color_dst_factor

Destination blending factor for the color channels

color_equation

Blending equation for the color channels

alpha_src_factor

Source blending factor for the alpha channel

alpha_dst_factor

Destination blending factor for the alpha channel

alpha_equation

Blending equation for the alpha channel

sfml.graphics.BLEND_ALPHA

Blend source and dest according to dest alpha

sfml.graphics.BLEND_ADD

Add source to dest

sfml.graphics.BLEND_MULTIPLY

Multiply source and dest

sfml.graphics.BLEND_NONE

Overwrite dest with source

Pixels

class sfml.graphics.Pixels
width
height
data

Image

class sfml.graphics.Image

Class for loading, manipulating and saving images.

Image is an abstraction to manipulate images as bidimensional arrays of pixels.

The class provides functions to load, read, write and save pixels, as well as many other useful functions.

Image 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 an Color. All the functions that return an array of pixels follow this rule, and all parameters that you pass to Image functions (such as from_pixels()) must use this representation as well.

A Image can be copied, but it is a heavy resource; keep it in mind!

For debugging purpose, you can call its method show() that displays its content in an external window in an external thread.

Usage example:

try:
   # load an image file from a file
   background = sf.Image.from_file("background.jpg")

except IOError: exit(1)

# create a 20x20 image filled with black color
image = sf.Image.create(20, 20, sf.Color.BLACK)

# copy image1 on image 2 at position(10, 10)
background.blit(image, (10, 10))

# make the top-left pixel transparent
color = image[0, 0]
color.a = 0
image[0, 0] = color

# save the image to a file
background.to_file("result.png")
classmethod create(width, height[, color])

Create the image and fill it with a unique color.

Parameters:
Return type:

sfml.graphics.Image
classmethod from_pixels(pixels)

Create the image from an array of pixels wrapped around Pixels. This function fails without raising error if pixels are invalid. On the other hand, it raises one if pixels points on NULL?

Raise:sfml.system.SFMLException - If pixels is empty.
Parameters:pixels (sfml.window.Pixels) – Array of pixels to copy to the image
Return type:sfml.graphics.Image
classmethod from_file(filename)

Load the image from a file on disk.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr and pic. Some format options are not supported, like progressive jpeg. If this function fails, it raises an exception.

Raise:IOError - The image failed to load
Parameters:filename (str) – Path of the image file to load
Return type:sfml.graphics.Image
classmethod from_memory(data)

Load the image from a file in memory.

The supported image formats are bmp, png, tga, jpg, gif, psd, hdr and pic. Some format options are not supported, like progressive jpeg. If this function fails, it raises an exception.

Raise:IOError - The image failed to load
Parameters:data (bytes) – The data to load, in bytes
Return type:sfml.graphics.Image
classmethod to_file(filename)

Save the image to a file on disk.

The format of the image is automatically deduced from the extension. The supported image formats are bmp, png, tga and jpg. The destination file is overwritten if it already exists.

Raise:IOError - If the image is empty
Parameters:filename (str) – Path of the file to save
show()

This function starts an external thread that displays the current content of the image in a window. It’s a very handy feature for debugging purpose only.

size

Return the size of the image.

Type:sfml.system.Vector2
width

Return the width of the image.

Type:integer
height

Return the width of the image.

Type:height
create_mask_from_color(color[, alpha=0])

Create a transparency mask from a specified color-key.

This function sets the alpha value of every pixel matching the given color to alpha (0 by default), so that they become transparent.

Parameters:
blit(source, dest[, source_rect=(0, 0, 0, 0)[, apply_alpha=False]])

Copy pixels from another image onto this one.

This function does a slow pixel copy and should not be used intensively. It can be used to prepare a complex static image from several others, but if you need this kind of feature in real-time you’d better use RenderTexture.

If source_rect is empty, the whole image is copied. If apply_alpha is set to true, the transparency of source pixels is applied. If it is false, the pixels are copied unchanged with their alpha value.

Parameters:
  • source (sfml.graphics.Image) – Source image to copy
  • dest (sfml.system.Vector2 or None) – Coordinate of the destination position
  • source_rect (sfml.graphics.Rectangle or tuple) – Sub-rectangle of the source image to copy
  • apply_alpha (bool) – Should the copy take in account the source transparency ?
pixels

Get a read-only pointer to the array of pixels. This pointer is wrapped around Pixels.

The returned value points to an array of RGBA pixels made of 8 bits integers components. The size of the array is width * height * 4.

Warning

The returned object may become invalid if you modify the image, so you should never store it for too long. If the image is empty, None is returned.

Type:sfml.window.Pixels or None
flip_horizontally()

Flip the image horizontally (left <-> right)

flip_vertically()

Flip the image vertically (top <-> bottom)

__getitem__()

Get a pixel from the image.

print(image[0,0])    # create tuple implicitly
print(image[(0,0)])  # create tuple explicitly
__setitem__()

Set a pixel of the image.

image[0,0]   = sfml.graphics.Color(10, 20, 30)  # create tuple implicitly
image[(0,0)] = sfml.graphics.Color(10, 20, 30)  # create tuple explicitly

Texture

class sfml.graphics.Texture

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

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 an Image, you need to prepare the pixels first and then upload them to the texture in a single operation (see Texture.update()).

Texture makes it easy to convert from/to 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 or a memory. 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 an Image, do whatever you need with the pixels, and then call Texture.from_image().

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 Image, 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 an Color.

Usage example:

This first example shows the most common use of Texture drawing a sprite

#load a texture from a file
try:
   texture = sf.Texture.from_file("texture.png")

except IOError: exit(1)

# assign it to a sprite
sprite = sf.Sprite(texture)

# draw the textured sprite
window.draw(sprite);

This second example shows another common use of Texture streaming real-time data, like video frames

# create an empty texture
texture = sf.Texture.create(640, 480)

# create a sprite that will display the texture
sprite = sf.Sprite(texture)

while loop: # the main loop
   # ...

   # get a fresh chunk of pixels (the next frame of a movie, for example)
   pixels = get_pixels_function()

   # update the texture
   texture.update(pixels)
   # or use update_from_pixels (faster)
   texture.update_from_pixels(pixels)

   # draw it
   window.draw(sprite)
   # ...
Texture()

The default constructor is not meant to be called. It will raise NotImplementedError with a message telling you that you must use a specific constructor.

Those specific constructors are: create(), from_file(), from_memory(), from_image().

NORMALIZED

Texture coordinates in range [0 .. 1].

PIXELS

Texture coordinates in range [0 .. size].

classmethod create(width, height)

Create a texture.

Parameters:
  • width (integer) – Width of the texture
  • height (integer) – Height of the texture
Return type:

sfml.graphics.Texture
classmethod from_file(filename[, area=(0, 0, 0, 0)])

Load the texture from a file on disk.

This function is a shortcut for the following code:

image = sf.Image.from_file(filename)
texture.from_image(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 Rectangle). 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 get_maximum_size() function.

If this function fails, it raises an exception.

Raise:

IOError - The texture failed to load
Parameters:
Return type:

sfml.graphics.Texture
classmethod from_memory(data, area=(0, 0, 0, 0))

Load the texture from a file in memory.

This function is a shortcut for the following code:

image = sf.Image.from_memory(data)
texture = sf.Texture.from_image(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 Rectangle). 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 get_maximum_size() function.

If this function fails, it raises an exception.

Raise:

IOError - The texture failed to load
Parameters:
Return type:

sfml.graphics.Texture
classmethod from_image(image[, area=(0, 0, 0, 0)])

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 Rectangle). 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 get_maximum_size() function.

If this function fails, it raises an error.

Raise:

sfml.system.SFMLException - The texture failed to load
Parameters:
Return type:

sfml.graphics.Texture
size

Return the size of the texture.

Type:sfml.system.Vector2
width

Return the width of the texture.

Type:integer
height

Return the height of the texture.

Type:integer
to_image()

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
Type:sfml.graphics.Image
update(*args, **kwargs)

Refer to update_from_pixels(), update_from_image() or update_from_window().

This method is provided for convenience, its sisters will be faster as they don’t have to check the argument’s type.

update_from_pixels(pixels[, position])

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.

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

Parameters:
update_from_image(image[, position])

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. Provide the additional argument position 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:
update_from_window(window[, position])

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. Provide the additional argument position 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:
bind(coordinate_type=sfml.graphics.Texture.NORMALIZED)

Activate the texture for rendering.

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

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:coordinate_type (sfml.graphics.Texture‘s constant) – Type of texture coordinates to use
smooth

Get/set 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.

Type: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.

Type:bool
classmethod get_maximum_size()

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
Return type:integer

Glyph

class sfml.graphics.Glyph

Structure describing a glyph.

A glyph is the visual representation of a character.

The Glyph structure provides the information needed to handle the glyph:

  • its coordinates in the font’s texture
  • its bounding rectangle
  • the offset to apply to get the starting position of the next glyph
Glyph()

Default constructor.

Return type:sfml.graphics.Glyph
advance

Offset to move horizontally to the next character.

Return type:integer
bounds

Bounding rectangle of the glyph, in coordinates relative to the baseline.

Return type:sfml.graphics.Rectangle
texture_rectangle

Texture coordinates of the glyph inside the font’s texture.

Return type:sfml.graphics.Rectangle

Font

class sfml.graphics.Font

Class for loading and manipulating character fonts.

Fonts can be loaded from a file or from memory, and supports the most common types of fonts.

See the from_file() function for the complete list of supported formats.

Once it is loaded, an Font instance provides three types of informations about the font:

  • Global metrics, such as the line spacing
  • Per-glyph metrics, such as bounding box or kerning
  • Pixel representation of glyphs

Fonts alone are not very useful: they hold the font data but cannot make anything useful of it. To do so you need to use the Text class, which is able to properly output text with several options such as character size, style, color, position, rotation, etc. This separation allows more flexibility and better performances: indeed an Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, an Text is a lightweight object which can combine the glyphs data and metrics of an Font to display any text on a render target. Note that it is also possible to bind several Text instances to the same Font.

It is important to note that the Text instance doesn’t copy the font that it uses, it only keeps a reference to it. Thus, an Font must not be destructed while it is used by an Text.

Usage example:

# declare a new font
try:
   font = sf.Font.from_file("arial.ttf")

except IOError: exit(1) # error...

# create a text which uses our font
text1 = sf.Text()
text1.font = font
text1.character_size = 30
text1.style = sf.Text.REGULAR

# create another text using the same font, but with different parameters
text2 = sf.Text()
text2.font = font
text2.character_size = 50
text2.style = sf.Text.ITALIC

Apart from loading font files, and passing them to instances of Text, you should normally not have to deal directly with this class. However, it may be useful to access the font metrics or rasterized glyphs for advanced usage.

Font()

The default constructor is not meant to be called. It will raise NotImplementedError with a message telling you that you must use a specific constructor.

Those specific constructors are: from_file() and from_memory().

classmethod from_file(filename)

Load the font from a file.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Note that this function know nothing about the standard fonts installed on the user’s system, thus you can’t load them directly.

This function raises an exception if it fails.

Raise:IOError - The font failed to load
Parameters:filename (str) – Path of the font file to load
Return type:sfml.graphics.Font
classmethod from_memory(data)

Load the font from a file in memory.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Note that this function know nothing about the standard fonts installed on the user’s system, thus you can’t load them directly.

This function raises an exception if it fails.

Raise:IOError - The font failed to load
Parameters:data (bytes) – The data to load
Return type:sfml.graphics.Font
get_glyph(code_point, character_size, bold)

Retrieve a glyph of the font.

Parameters:
  • code_point (integer) – Unicode code point of the character to get
  • character_size (integer) – Reference character size
  • bold (bool) – Retrieve the bold version or the regular one ?
Returns:

The glyph corresponding to code_point and character_size
Return type:

sfml.graphics.Glyph
get_kerning(first, second, character_size)

Get the kerning offset of two glyphs.

The kerning is an extra offset (negative) to apply between two glyphs when rendering them, to make the pair look more “natural”. For example, the pair “AV” have a special kerning to make them closer than other characters. Most of the glyphs pairs have a kerning offset of zero, though.

Parameters:
  • first (integer) – Unicode code point of the first character
  • second (integer) – Unicode code point of the second character
  • character_size (integer) – Reference character size
Returns:

Kerning value for first and second, in pixels
Return type:

integer
get_line_spacing(character_size)

Get the line spacing.

Line spacing is the vertical offset to apply between two consecutive lines of text.

Parameters:character_size (integer) – Reference character size
Returns:Line spacing, in pixels
Return type:integer
get_texture(character_size)

Retrieve the texture containing the loaded glyphs of a certain size.

The contents of the returned texture changes as more glyphs are requested, thus it is not very relevant. It is mainly used internally by Text.

Parameters:character_size (integer) – Reference character size
Returns:Texture containing the glyphs of the requested size
Return type:sfml.graphics.Texture
info

Various information about a font.

Returns:A string containing the font family
Return type:str

Shader

class sfml.graphics.Shader

Shader class (vertex and fragment)

Shaders are programs written using a specific language, executed directly by the graphics card and allowing to apply real-time operations to the rendered entities.

There are two kinds of shaders:

  • Vertex shaders, that process vertices
  • Fragment (pixel) shaders, that process pixels

A Shader can be composed of either a vertex shader alone, a fragment shader alone, or both combined (see the variants of the load functions).

Shaders are written in GLSL, which is a C-like language dedicated to OpenGL shaders. You’ll probably need to learn its basics before writing your own shaders for pySFML.

Like any C/C++ program, a shader has its own variables that you can set from your Python application. Shader handles 4 different types of variables:

  • floats
  • vectors (2, 3 or 4 components)
  • textures
  • transforms (matrices)
Shader()

The default constructor is not meant to be called. It will raise NotImplementedError with a message telling you that you must use a specific constructor.

Those specific constructors are: from_file() and from_memory().

classmethod from_file(vertex_filename=None, fragment_filename=None)

Load a vertex shader or a fragment shader or both from files.

The sources must be text files containing valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

Raise:

IOError - If one of the two shaders failed to load
Parameters:
  • vertex_filename (str) – Path of the vertex or fragment shader file to load
  • fragment_filename (str) – Path of the fragment shader file to load
Return type:

sfml.graphics.Shader
classmethod from_memory(vertex_shader=None, fragment_shader=None)

Load a vertex shader or a fragment shader or both from source codes in memory.

This function loads both the vertex and the fragment shaders. If one of them fails to load, the error IOError is raised. The sources must be valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you’ll probably need to read a good documentation for it before writing your own shaders.

Raise:

IOError - If one of the two shaders failed to load
Parameters:
  • vertex_shader (str) – String containing the source code of the vertex shader
  • fragment_shader (str) – String containing the source code of the fragment shader
Return type:

sfml.graphics.Shader
set_parameter(*args, **kwargs)

This method takes care of calling the suitable set_parameter method. See the table below:

Parameters Method
1 float set_1float_parameter()
2 float set_2float_parameter()
3 float set_3float_parameter()
4 float set_4float_parameter()
Vector2 set_vector2_parameter()
Vector3 set_vector3_parameter()
Color set_color_parameter()
Transform set_transform_parameter()
Texture set_texture_parameter()
CURRENT_TEXTURE set_currenttexturetype_parameter()
set_1float_parameter(name, x)

Change a float parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a float (float GLSL type).

Example:

uniform float myparam; // this is the variable in the shader

shader.set_1float_parameter("myparam", 5.2) # using the specific method (faster)
shader.set_parameter("myparam", 5.2)        # using the general method
Parameters:
  • name (str) – Name of the parameter in the shader
  • x (float) – Value to assign
set_2float_parameter(name, x, y)

Change a 2-components vector parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 2x1 vector (vec2 GLSL type).

Example:

uniform vec2 myparam; // this is the variable in the shader

shader.set_2float_parameter("myparam", 5.2, 6) # using the specific method (faster)
shader.set_parameter("myparam", 5.2, 6)        # using the general method
Parameters:
  • name (str) – Name of the parameter in the shader
  • x (float) – First component of the value to assign
  • y (float) – Second component of the value to assign
set_3float_parameter(name, x, y, z)

Change a 3-components vector parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 3x1 vector (vec3 GLSL type).

Example:

uniform vec3 myparam; // this is the variable in the shader

shader.set_3float_parameter("myparam", 5.2, 6, -8.1) # using the specific method (faster)
shader.set_parameter("myparam", 5.2, 6, -8.1)        # using the general method
Parameters:
  • name (str) – Name of the parameter in the shader
  • x (float) – First component of the value to assign
  • y (float) – Second component of the value to assign
  • z (float) – Third component of the value to assign
set_4float_parameter(name, x, y, z, w)

Change a 4-components vector parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 4x1 vector (vec4 GLSL type).

Example:

uniform vec4 myparam; // this is the variable in the shader

shader.set_4float_parameter("myparam", 5.2, 6, -8.1, 0.4) # using the specific method (faster)
shader.set_parameter("myparam", 5.2, 6, -8.1, 0.4)        # using the general method
Parameters:
  • name (str) – Name of the parameter in the shader
  • x (float) – First component of the value to assign
  • y (float) – Second component of the value to assign
  • z (float) – Third component of the value to assign
  • w (float) – Fourth component of the value to assign
set_vector2_parameter(name, vector)

Change a 2-components vector parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 2x1 vector (vec2 GLSL type).

Example:

uniform vec2 myparam; // this is the variable in the shader

shader.set_vector2_parameter("myparam", sf.Vector2(5.2, 6)) # using the specific method (faster)
shader.set_parameter("myparam", sf.Vector2(5.2, 6))         # using the general method
shader.set_parameter("myparam", (5.2, 6))                   # using tuple works too
Parameters:
  • name (str) – Name of the parameter in the shader
  • vector (sfml.system.Vector2) – Vector to assign
set_vector3_parameter(name, vector)

Change a 3-components vector parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 3x1 vector (vec3 GLSL type).

Example:

uniform vec3 myparam; // this is the variable in the shader

shader.set_vector3_parameter("myparam", sf.Vector3(5.2, 6, -8.1)) # using the specific method (faster)
shader.set_parameter("myparam", sf.Vector3(5.2, 6, -8.1))         # using the general method
shader.set_parameter("myparam", (5.2, 6, -8.1))                   # using tuple works too
Parameters:
  • name (str) – Name of the parameter in the shader
  • vector (sfml.system.Vector3) – Vector to assign
set_color_parameter(name, color)

Change a color parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 4x1 vector (vec4 GLSL type).

It is important to note that the components of the color are normalized before being passed to the shader. Therefore, they are converted from range [0 .. 255] to range [0 .. 1]. For example, a sf.Color(255, 125, 0, 255) will be transformed to a vec4(1.0, 0.5, 0.0, 1.0) in the shader.

Example:

uniform vec4 color; // this is the variable in the shader

shader.set_color_parameter("myparam", sf.Color(255, 128, 0, 255)) # using the specific method (faster)
shader.set_parameter("myparam", sf.Color(255, 128, 0, 255))       # using the general method
Parameters:
  • name (str) – Name of the parameter in the shader
  • color (sfml.graphics.Color) – Color to assign
set_transform_parameter(name, transform)

Change a matrix parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 4x4 matrix (mat4 GLSL type).

Example:

uniform mat4 matrix; // this is the variable in the shader

transform = sf.Transform()
transform.translate(sf.Vector2(5, 10))

shader.set_transform_parameter("matrix", transform) # using the specific method (faster)
shader.set_parameter("matrix", transform)           # using the general method
Parameters:
set_texture_parameter(name, texture)

Change a texture parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 2D texture (sampler2D GLSL type).

Example:

uniform sampler2D the_texture; // this is the variable in the shader

texture = sf.Texture.create(50, 50)
# ...

shader.set_texture_parameter("the_texture", texture) # using the specific method (faster)
shader.set_parameter("the_texture", texture)         # using the general method

It is important to note that texture must remain alive as long as the shader uses it, no copy is made internally.

To use the texture of the object being draw, which cannot be known in advance, use set_currenttexturetype_parameter().

Parameters:
  • name (str) – Name of the parameter in the shader
  • texture (sfml.graphics.Texture) – Texture to assign
set_currenttexturetype_parameter(name)

Change a texture parameter of the shader.

This overload maps a shader texture variable to the texture of the object being drawn, which cannot be known in advance. The corresponding parameter in the shader must be a 2D texture (sampler2D GLSL type).

Example:

uniform sampler2D current; // this is the variable in the shader

shader.set_currenttexturetype_parameter("current") # using the specific method (faster)
shader.set_parameter("current")                    # using the general method
bind()

Bind the shader for rendering (activate it)

This function is normally for internal use only, unless you want to use the shader with a custom OpenGL rendering instead of a pySFML drawable.

window.active = True
shader.bind()
# ... render OpenGL geometry ...
shader.unbind()

RenderStates

class sfml.graphics.RenderStates

Define the states used for drawing to a RenderTarget.

There are four global states that can be applied to the drawn objects:

  • the blend mode: how pixels of the object are blended with the background
  • the transform: how the object is positioned/rotated/scaled
  • the texture: what image is mapped to the object
  • the shader: what custom effect is applied to the object

High-level objects such as sprites or text force some of these states when they are drawn. For example, a sprite will set its own texture, so that you don’t have to care about it when drawing the sprite.

The transform is a special case: sprites, texts and shapes (and it’s a good idea to do it with your own drawable classes too) combine their transform with the one that is passed in the RenderStates structure. So that you can use a “global” transform on top of each object’s transform.

Most objects, especially high-level drawables, can be drawn directly without defining render states explicitly – the default set of states is ok in most cases.

window.draw(sprite)

If you want to use a single specific render state, for example a shader, you can pass it directly to the draw function.

window.draw(sprite, shader)

When you’re inside the draw function of a drawable object (inherited from Drawable), you can either pass the render states unmodified, or change some of them. For example, a transformable object will combine the current transform with its own transform. A sprite will set its texture. Etc.

RenderStates(blendmode=BLEND_ALPHA[, transform[, texture[, shader]]])

Construct a default render states with custom values.

Parameters:
Return type:

sfml.graphics.RenderStates
DEFAULT

Special instance holding the default render states.

blendmode

Blending mode.

transform

Transform.

texture

Texture.

shader

Shader.

Drawable

class sfml.graphics.Drawable

Abstract base class for objects that can be drawn to a render target.

Drawable is a very simple base class that allows objects of derived classes to be drawn to an RenderTarget.

All you have to do in your derived class is to override the draw virtual function.

Note that inheriting from Drawable is not mandatory, but it allows this nice syntax “window.draw(object)” rather than “object.draw(window)”, which is more consistent with other pySFML classes.

Example:

class MyDrawable(sf.Drawable):
   def __init__(self):
      sf.Drawable.__init__(self)
      # ...

   def draw(self, target, states):
      # you can draw other high-level objects
      target.draw(self.sprite, states)

      # ... or use the low-level API
      states.texture = self.texture
      target.draw(self.vertices, states)

      # ... or draw with OpenGL directly
      glBegin(GL_QUADS)
         # ...
      glEnd()
draw(target, states):

Draw the object to a render target.

This is a virtual method that has to be implemented by the derived class to define how the drawable should be drawn.

Parameters:

Transformable

class sfml.graphics.Transformable

Decomposed transform defined by a position, a rotation and a scale.

This class is provided for convenience, on top of Transform.

Transform, as a low-level class, offers a great level of flexibility but it is not always convenient to manage. Indeed, one can easily combine any kind of operation, such as a translation followed by a rotation followed by a scaling, but once the result transform is built, there’s no way to go backward and, let’s say, change only the rotation without modifying the translation and scaling. The entire transform must be recomputed, which means that you need to retrieve the initial translation and scale factors as well, and combine them the same way you did before updating the rotation. This is a tedious operation, and it requires to store all the individual components of the final transform.

That’s exactly what Transformable was written for: it hides these variables and the composed transform behind an easy to use interface. You can set or get any of the individual components without worrying about the others. It also provides the composed transform (as an Transform), and keeps it up-to-date.

In addition to the position, rotation and scale, Transformable provides an “origin” component, which represents the local origin of the three other components. Let’s take an example with a 10x10 pixels sprite. By default, the sprite is positioned/rotated/scaled relatively to its top-left corner, because it is the local point (0, 0). But if we change the origin to be (5, 5), the sprite will be positioned/rotated/scaled around its center instead. And if we set the origin to (10, 10), it will be transformed around its bottom-right corner.

To keep the Transformable class simple, there’s only one origin for all the components. You cannot position the sprite relatively to its top-left corner while rotating it around its center, for example. To do such things, use Transform directly.

Transformable can be used as a base class. It is often combined with Drawable – that’s what SFML’s sprites, texts and shapes do.

class MyEntity(sf.TransformableDrawable):
   def draw(self, target, states):
      sf.TransformableDrawable.draw(self, target, states)
      states.transform *= get_transform()
      target.draw(..., states)

entity = MyEntity()
entity.position = (10, 20)
entity.rotation = 45
window.draw(entity)
Transformable()

Default constructor.

Return type:sfml.graphics.Transformable
position

Set/get the position of the object

This attribute completely overwrites the previous position. See move() to apply an offset based on the previous position instead. The default position of a transformable object is (0, 0).

Return type:sfml.system.Vector2
rotation

Set/get the orientation of the object

This attribute completely overwrites the previous rotation. See rotate() to add an angle based on the previous rotation instead. The default rotation of a transformable object is 0.

Return type:float
ratio

Set/get the scale factors of the object

This function completely overwrites the previous ratio. See scale() to add a factor based on the previous scale instead. The default scale of a transformable object is (1, 1).

Return type:sfml.system.Vector2
origin

Set/get the local origin of the object

The origin of an object defines the center point for all transformations (position, scale, rotation). The coordinates of this point must be relative to the top-left corner of the object, and ignore all transformations (position, scale, rotation). The default origin of a transformable object is (0, 0).

Return type:sfml.system.Vector2
move(offset)

Move the object by a given offset.

This function adds to the current position of the object, unlike position which overwrites it. Thus, it is equivalent to the following code:

object.position = object.position + offset
Parameters:offset (sfml.system.Vector2) – Offset
rotate(angle)

Rotate the object.

This function adds to the current rotation of the object, unlike rotation which overwrites it. Thus, it is equivalent to the following code:

object.rotation = object.rotation + angle
scale(factor)

Scale the object.

This function multiplies the current scale of the object, unlike ratio which overwrites it. Thus, it is equivalent to the following code:

object.ratio = object.ratio * factor
transform

Get the combined transform of the object.

Return type:sfml.graphics.Transform
inverse_transform

Get the inverse of the combined transform of the object.

Return type:sfml.graphics.Transform

Sprite

class sfml.graphics.Sprite(sfml.graphics.Drawable, sfml.graphics.Transformable)

Drawable representation of a texture, with its own transformations, color, etc.

Sprite is a drawable class that allows to easily display a texture (or a part of it) on a render target.

It inherits all the functions from Transformable: position, rotation, scale, origin. It also adds sprite-specific properties such as the texture to use, the part of it to display, and some convenience functions to change the overall color of the sprite, or to get its bounding rectangle.

Sprite works in combination with the Texture class, which loads and provides the pixel data of a given texture.

The separation of Sprite and Texture allows more flexibility and better performances: indeed a Texture is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, an Sprite is a lightweight object which can use the pixel data of an Texture and draw it with its own transformation/color/blending attributes.

It is important to note that the Sprite instance doesn’t copy the texture that it uses, it only keeps a reference to it. Thus, an Texture must not be destroyed while it is used by an Sprite.

Usage examples:

# declare and load a texture
try: texture = sf.Texture.from_file("texture.png")
except IOError: exit(1)

# create a sprite
sprite = sf.Sprite(texture)
sprite.texture_rectangle = sf.Rectangle((10, 10), (50, 30))
sprite.color = sf.Color(255, 255, 255, 200)
sprite.position = sf.Vector2(100, 25)

# draw it
window.draw(sprite)
Sprite(texture[, rectangle])

Construct the sprite from (a sub-rectangle of) a source texture.

Parameters:
texture

Change the source texture of the sprite.

The texture argument refers to a texture that must exist as long as the sprite uses it. Indeed, the sprite doesn’t store its own copy of the texture, but rather keeps a pointer to the one that you passed to this function. If the source texture is destroyed and the sprite tries to use it, the behaviour is undefined. The texture_rectangle property of the sprite is automatically adjusted to the size of the new texture

Note

Note that in C++, you must explicitly tell you want the texture rectangle to be reset. Here, the texture rectangle is reset by default.

Return type:sfml.graphics.Texture
texture_rectangle

Set/get the sub-rectangle of the texture that the sprite will display.

The texture rectangle is useful when you don’t want to display the whole texture, but rather a part of it. By default, the texture rectangle covers the entire texture.

color

Set/get the global color of the sprite.

This color is modulated (multiplied) with the sprite’s texture. It can be used to colorize the sprite, or change its global opacity. By default, the sprite’s color is opaque white.

local_bounds

Get the local bounding rectangle of the entity.

The returned rectangle is in local coordinates, which means that it ignores the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the entity in the entity’s coordinate system.

Return type:sfml.graphics.Rectangle
global_bounds

Get the global bounding rectangle of the entity.

The returned rectangle is in global coordinates, which means that it takes in account the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the sprite in the global 2D world’s coordinate system.

Return type:sfml.graphics.Rectangle

Text

class sfml.graphics.Text(sfml.graphics.Drawable, sfml.graphics.Transformable)

Graphical text that can be drawn to a render target.

Text is a drawable class that allows to easily display some text with custom style and color on a render target.

It inherits all the functions from Transformable: position, ratio, scale, origin. It also adds text-specific properties such as the font to use, the character size, the font style (bold, italic, underlined, strike through), the global color and the text to display of course. It also provides convenience functions to calculate the graphical size of the text, or to get the global position of a given character.

Text works in combination with the Font class, which loads and provides the glyphs (visual characters) of a given font.

The separation of Font and Text allows more flexibility and better performances: indeed a Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a Text is a lightweight object which can combine the glyphs data and metrics of an Font to display any text on a render target.

It is important to note that the Text instance doesn’t copy the font that it uses, it only keeps a reference to it. Thus, an Font must not be destructed while it is used by an Text.

Usage example:

# declare and load a font
try: font = sf.Font.from_file("arial.ttf")
except IOError: exit(1)

# create a text
text = sf.Text("hello")
text.font = font
text.character_size = 30
text.style = sf.Text.BOLD
text.color = sf.Color.RED

# draw it
window.draw(text)
Style Description
REGULAR Regular characters, no style
BOLD Bold characters
ITALIC Italic characters
UNDERLINED Underlined characters
STRIKE_THROUGH Strike through characters
Text([string[, font[, character_size=30]]])

Construct the string, and optionally from a string, font and size.

Parameters:
  • str – Text assigned to the string
  • font (sfml.graphics.Font) – Font used to draw the string
  • character_size (integer) – Base size of characters, in pixels
REGULAR

Regular characters, no style.

BOLD

Bold characters.

ITALIC

Italic characters.

UNDERLINED

Underlined characters.

STRIKE_THROUGH

Strike through characters.

string

Set/get the text’s string.

Return type:bytes or string
font

Set/get the text’s font.

The font argument refers to a font that must exist as long as the text uses it. Indeed, the text doesn’t store its own copy of the font, but rather keeps a reference to the one that you set to this attribute. If the font is destroyed and the text tries to use it, the behaviour is undefined.

Return type:sfml.graphics.Font
character_size

Set/get the character size.

The default size is 30.

Return type:integer
style

Set/get the text’s style.

You can pass a combination of one or more styles, for example

text.style = sf.Text.BOLD | sf.Text.ITALIC

The default style is REGULAR.

Return type:integer
color

Set/get the global color of the text.

By default, the text’s color is opaque white.

Return type:sfml.graphics.Color
local_bounds

Get the local bounding rectangle of the entity.

The returned rectangle is in local coordinates, which means that it ignores the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this property returns the bounds of the entity in the entity’s coordinate system.

Return type:sfml.graphics.Rectangle
global_bounds

Get the global bounding rectangle of the entity.

The returned rectangle is in global coordinates, which means that it takes in account the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this property returns the bounds of the text in the global 2D world’s coordinate system.

Return type:sfml.graphics.Rectangle
find_character_pos(index)

Return the position of the index-th character.

This function computes the visual position of a character from its index in the string. The returned position is in global coordinates (translation, rotation, scale and origin are applied). If index is out of range, the position of the end of the string is returned.

Parameters:index (integer) – Index of the character
Returns:Position of the character
Return type:sfml.system.Vector2

Shape

class sfml.graphics.Shape(sfml.graphics.Drawable, sfml.graphics.Transformable)

Base class for textured shapes with outline.

Shape is a drawable class that allows to define and display a custom convex shape on a render target.

It’s only an abstract base, it needs to be specialized for concrete types of shapes (circle, rectangle, convex polygon, star, ...).

In addition to the attributes provided by the specialized shape classes, a shape always has the following attributes:

  • a texture
  • a texture rectangle
  • a fill color
  • an outline color
  • an outline thickness

Each feature is optional, and can be disabled easily:

  • the texture can be null
  • the fill/outline colors can be Color.TRANSPARENT
  • the outline thickness can be zero
Shape()

Shape is abstract, it would raise an error NotImplementedError

texture

Change or get the source texture of the shape.

The texture argument refers to a texture that must exist as long as the shape uses it. Indeed, the shape doesn’t store its own copy of the texture, but rather keeps a pointer to the one that y ou passed to this function. If the source texture is destroyed and the shape tries to use it, the behaviour is undefined. texture can be None to disable texturing. The texture_rectangle property of the shape is automatically adjusted to the size of the new texture.

Note

Note that in C++, you must explicitly tell you want the texture rectangle to be reset. Here, the texture rectangle is reset by default.

Return type:sfml.graphics.Texture or None
texture_rectangle

Set/get the sub-rectangle of the texture that the shape will display.

The texture rectangle is useful when you don’t want to display the whole texture, but rather a part of it. By default, the texture rectangle covers the entire texture.

Return type:sfml.graphics.Rectangle
fill_color

Set/get the fill color of the shape.

This color is modulated (multiplied) with the shape’s texture if any. It can be used to colorize the shape, or change its global opacity. You can use Color.TRANSPARENT to make the inside of the shape transparent, and have the outline alone. By default, the shape’s fill color is opaque white.

Return type:sfml.graphics.Color
outline_color

Set/get the outline color of the shape.

You can use Color.TRANSPARENT to disable the outline. By default, the shape’s outline color is opaque white.

Return type:sfml.graphics.Color
outline_thickness

Set/get the thickness of the shape’s outline.

This number cannot be negative. Using zero disables the outline. By default, the outline thickness is 0.

Return type:float
local_bounds

Get the local bounding rectangle of the entity.

The returned rectangle is in local coordinates, which means that it ignores the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the entity in the entity’s coordinate system.

Return type:sfml.graphics.Rectangle
global_bounds

Get the global bounding rectangle of the entity.

The returned rectangle is in global coordinates, which means that it takes in account the transformations (translation, rotation, scale, ...) that are applied to the entity. In other words, this function returns the bounds of the sprite in the global 2D world’s coordinate system.

Return type:sfml.graphics.Rectangle

CircleShape

class sfml.graphics.CircleShape(sfml.graphics.Shape)

Specialized shape representing a circle.

This class inherits all the functions of Transformable (position, rotation, scale, bounds, ...) as well as the functions of Shape (outline, color, texture, ...).

Usage example:

circle = sf.CircleShape()
circle.radius = 150
circle.outline_color = sf.Color.RED
circle.outline_thickness = 5
circle.position = (10, 20)
# ...

window.draw(circle)

Since the graphics card can’t draw perfect circles, we have to fake them with multiple triangles connected to each other. The “points count” property of CircleShape defines how many of these triangles to use, and therefore defines the quality of the circle.

The number of points can also be used for another purpose; with small numbers you can create any regular polygon shape: equilateral triangle, square, pentagon, hexagon, ...

CircleShape([radius[, point_count])

Default constructor.

Parameters:
  • radius (float) – Radius of the circle
  • point_count (integer) – Number of points composing the circle
radius

Set/get the radius of the circle.

Return type:float
point_count

Set/get the number of points of the circle.

Return type:integer
get_point(index)

Get a point of the shape.

The result is undefined if index is out of the valid range.

Parameters:index (integer) – Index of the point to get, in range [0 .. point_count - 1]
Returns:Index-th point of the shape
Return type:sfml.system.Vector2

ConvexShape

class sfml.graphics.ConvexShape(sfml.graphics.Shape)

Specialized shape representing a convex polygon.

This class inherits all the functions of Transformable (position, rotation, scale, bounds, ...) as well as the functions of Shape (outline, color, texture, ...).

It is important to keep in mind that a convex shape must always be... convex, otherwise it may not be drawn correctly. Moreover, the points must be defined in order; using a random order would result in an incorrect shape.

Usage example:

polygon = sf.ConvexShape()
polygon.point_count = 3
polygon.set_point(0, (0, 0))
polygon.set_point(1, (0, 10))
polygon.set_point(2, (25, 5))
polygon.outline_color = sf.Color.RED
polygon.outline_thickness = 5
polygon.position = (10, 20)
# ...
window.draw(polygon)
ConvexShape()

Default constructor.

point_count

Set/get the number of points of the polygon.

count must be greater than 2 to define a valid shape.

Return type:integer
get_point(index)

Get the position of a point.

The result is undefined if index is out of the valid range.

Parameters:index (integer) – Index of the point to get, in range [0 .. point_count - 1]
Returns:Vector2 of the index-th point of the polygon
Return type:sfml.system.Vector2
set_point(index, point)

Set the position of a point.

Don’t forget that the polygon must remain convex, and the points need to stay ordered! point_count must be called first in order to set the total number of points. The result is undefined if index is out of the valid range.

Parameters:

RectangleShape

class sfml.graphics.RectangleShape(sfml.graphics.Shape)

Specialized shape representing a rectangle.

This class inherits all the functions of Transformable (position, rotation, scale, bounds, ...) as well as the functions of Shape (outline, color, texture, ...).

Usage example:

rectangle = sf.RectangleShape()
rectangle.size = (100, 50)
rectangle.outline_color = sf.Color.RED
rectangle.outline_thickness = 5
rectangle.position = (10, 20)
# ...

window.draw(rectangle)
RectangleShape([size])

Default constructor.

Parameters:size (sfml.system.Vector2) – Size of the rectangle
size

Set/get the size of the rectangle.

Return type:sfml.system.Vector2
point_count

Get the number of points defining the shape.

Return type:integer
get_point(index)

Get the position of a point.

The result is undefined if index is out of the valid range.

Parameters:index (integer) – Index of the point to get, in range [0 .. point_count - 1]
Returns:Vector2 of the index-th point of the shape
Return type:sfml.system.Vector2

Vertex

class sfml.graphics.Vertex

Define a point with color and texture coordinates.

A vertex is an improved point.

It has a position and other extra attributes that will be used for drawing: in pySFML, vertices also have a color and a pair of texture coordinates.

The vertex is the building block of drawing. Everything which is visible on screen is made of vertices. They are grouped as 2D primitives (triangles, quads, ...), and these primitives are grouped to create even more complex 2D entities such as sprites, texts, etc.

If you use the graphical entities of pySFML (sprite, text, shape) you won’t have to deal with vertices directly. But if you want to define your own 2D entities, such as tiled maps or particle systems, using vertices will allow you to get maximum performances.

Example

# define a 100x100 square, red, with a 10x10 texture mapped on it
sf.Vertex(sf.Vector2(  0,   0), sf.Color.RED, sf.Vector2( 0,  0))
sf.Vertex(sf.Vector2(  0, 100), sf.Color.RED, sf.Vector2( 0, 10))
sf.Vertex(sf.Vector2(100, 100), sf.Color.RED, sf.Vector2(10, 10))
sf.Vertex(sf.Vector2(100,   0), sf.Color.RED, sf.Vector2(10,  0))

# all arguments are optional
sf.Vertex()
sf.Vertex(color=sf.Color.RED)
sf.Vertex((50, 100), sf.Color.BLUE)
sf.Vertex(tex_coords=(20, 20))

Note: although texture coordinates are supposed to be an integer amount of pixels, their type is float because of some buggy graphics drivers that are not able to process integer coordinates correctly.

Vertex([position[, color[, tex_coords]]])

Construct the vertex from its position, color and texture coordinates.

Parameters:
position

2D position of the vertex

Return type:sfml.system.Vector2
color

Color of the vertex.

Return type:sfml.graphics.Color
tex_coords

Coordinates of the texture’s pixel to map to the vertex.

Return type:sfml.system.Vector2

VertexArray

class sfml.graphics.VertexArray(sfml.graphics.Drawable)

Define a set of one or more 2D primitives.

VertexArray is a very simple wrapper around a dynamic array of vertices and a primitives type.

It inherits Drawable, but unlike other drawables it is not transformable.

Example:

lines = sf.VertexArray(sf.PrimitiveType.LINES_STRIP, 2)
lines[0].position = (10, 0)
lines[1].position = (20, 0)

lines.append(sf.Vertex((30, 5)))

lines.resize(4)
lines[3].position = (40, 2)

window.draw(lines)
VertexArray([type[, vertex_count]])

Construct the vertex array with a type and an initial number of vertices.

Parameters:
__len__()

Return the vertex count.

__getitem__(index)

Get an access to a vertex by its index.

__setitem__(index, vertex)

Set a vertex by its index.

clear()

Clear the vertex array.

This method removes all the vertices from the array. It doesn’t deallocate the corresponding memory, so that adding new vertices after clearing doesn’t involve reallocating all the memory.

resize(vertex_count)

Resize the vertex array.

If vertex_count is greater than the current size, the previous vertices are kept and new (default-constructed) vertices are added. If vertex_count is less than the current size, existing vertices are removed from the array.

append()

Add a vertex to the array.

primitive_type:

Set/get the type of primitives to draw.

This defines how the vertices must be interpreted when it’s time to draw them:

  • As points
  • As lines
  • As triangles
  • As quads

The default primitive type is POINTS.

Return type:sfml.graphics.PrimitiveType
bounds

Compute the bounding rectangle of the vertex array.

This returns the axis-aligned rectangle that contains all the vertices of the array.

Return type:sfml.graphics.Rectangle

View

class sfml.graphics.View

2D camera that defines what region is shown on screen

View defines a camera in the 2D scene.

This is a very powerful concept: you can scroll, rotate or zoom the entire scene without altering the way that your drawable objects are drawn.

A view is composed of a source rectangle, which defines what part of the 2D scene is shown, and a target viewport, which defines where the contents of the source rectangle will be displayed on the render target (window or texture).

The viewport allows to map the scene to a custom part of the render target, and can be used for split-screen or for displaying a minimap, for example. If the source rectangle has not the same size as the viewport, its contents will be stretched to fit in.

To apply a view, you have to assign it to the render target. Then, every objects drawn in this render target will be affected by the view until you use another view.

Usage example:

view = sf.View()

# initialize the view to a rectangle located at (100, 100) and with a size of 400x200
view.reset(sf.Rectangle((100, 100), (400, 200)))

# rotate it by 45 degrees
view.rotate(45)

# set its target viewport to be half of the window
view.viewport = sf.Rectangle((0, 0), (0.5, 1))

# apply it
window.view = view

# render stuff
window.draw(some_sprites)

# set the default view back
window.view = window.default_view

# render stuff not affected by the view
window.draw(some_text)
View([rectangle])

Construct the view, and optionally from a rectangle.

Parameters:rectangle (sfml.graphics.Rectangle) – Rectangle defining the zone to display
center

Set/get the center of the view.

Return type:sfml.system.Vector2
size

Set/get the size of the view.

Return type:sfml.system.Vector2
rotation

Set/get the orientation of the view.

The default rotation of a view is 0 degree.

Return type:float
viewport

Set/get the target viewport.

The viewport is the rectangle into which the contents of the view are displayed, expressed as a factor (between 0 and 1) of the size of the RenderTarget to which the view is applied. For example, a view which takes the left side of the target would be defined with view.viewport = (0, 0, 0.5, 1). By default, a view has a viewport which covers the entire target.

reset(rectangle)

Reset the view to the given rectangle.

Note that this function resets the rotation angle to 0.

Parameters:rectangle (sfml.graphics.Rectangle) – Rectangle defining the zone to display
move(offset)

Move the view relatively to its current position.

Parameters:offset (sfml.system.Vector2) – Move offset
rotate(angle)

Rotate the view relatively to its current orientation.

Parameters:angle (float) – Angle to rotate, in degrees
zoom(factor)

Resize the view rectangle relatively to its current size.

Resizing the view simulates a zoom, as the zone displayed on screen grows or shrinks. factor is a multiplier:

  • 1 keeps the size unchanged
  • > 1 makes the view bigger (objects appear smaller)
  • < 1 makes the view smaller (objects appear bigger)
Parameters:factor (float) – Zoom factor to apply
transform

Get the projection transform of the view.

This function is meant for internal use only.

Returns:Projection transform defining the view
Return type:sfml.graphics.Transform
inverse_transform

Get the inverse projection transform of the view.

This function is meant for internal use only.

Returns:Inverse of the projection transform defining the view
Return type:sfml.graphics.Transform

RenderTarget

class sfml.graphics.RenderTarget

Base class for all render targets (window, texture, ...)

RenderTarget defines the common behaviour of all the 2D render targets usable in the graphics module.

It makes it possible to draw 2D entities like sprites, shapes, text without using any OpenGL command directly.

A RenderTarget is also able to use views (View), which are a kind of 2D cameras. With views you can globally scroll, rotate or zoom everything that is drawn, without having to transform every single entity. See the documentation of View for more details and sample pieces of code about this class.

On top of that, render targets are still able to render direct OpenGL stuff. It is even possible to mix together OpenGL calls and regular SFML drawing commands. When doing so, make sure that OpenGL states are not messed up by calling the push_GL_states()/pop_GL_states() functions.

RenderTarget()

This class is abstract.

clear([color=sfml.graphics.Color(0, 0, 0, 255)])

Clear the entire target with a single color.

This function is usually called once every frame, to clear the previous contents of the target.

Parameters:color (sfml.graphics.Color) – Fill color to use to clear the render target
view

Change or get the current active view.

The view is like a 2D camera, it controls which part of the 2D scene is visible, and how it is viewed in the render-target. The new view will affect everything that is drawn, until another view is set. The render target keeps its own copy of the view object, so it is not necessary to keep the original one alive after calling this function. To restore the original view of the target, you can set the result of default_view to this attribute.

Return type:sfml.graphics.View
default_view

Get the default view of the render target.

The default view has the initial size of the render target, and never changes after the target has been created.

get_viewport(view)

Get the viewport of a view, applied to this render target.

The viewport is defined in the view as a ratio, this function simply applies this ratio to the current dimensions of the render target to calculate the pixels rectangle that the viewport actually covers in the target.

Parameters:view (sfml.graphics.View) – The view for which we want to compute the viewport
Returns:Viewport rectangle, expressed in pixels
Return type:sfml.graphics.Rectangle
convert_coords(point[, view])

Convert a point from target coordinates to view coordinates.

Initially, a unit of the 2D world matches a pixel of the render target. But if you define a custom view, this assertion is not true anymore, ie. a point located at (10, 50) in your render target (for example a window) may map to the point (150, 75) in your 2D world – for example if the view is translated by (140, 25).

For render windows, this function is typically used to find which point (or object) is located below the mouse cursor.

It uses a custom view for calculations if provided, otherwise, it uses the current view of the render target.

Parameters:
Returns:

The converted point, in “world” units
Return type:

sfml.system.Vector2
draw(drawable[, states])

Draw a drawable object to the render-target.

Parameters:
size

Return the size of the rendering region of the target.

Return type:sfml.system.Vector2
width

Return the width of the rendering region of the target.

Return type:integer
height

Return the height of the rendering region of the target.

Return type:integer
push_GL_states()

Save the current OpenGL render states and matrices.

This function can be used when you mix pySFML drawing and direct OpenGL rendering. Combined with pop_GL_states(), it ensures that:

  • pySFML’s internal states are not messed up by your OpenGL code
  • your OpenGL states are not modified by a call to a pySFML function

More specifically, it must be used around code that calls draw() functions. Example:

# OpenGL code here...
window.push_GL_state()
window.draw(...)
window.draw(...)
window.pop_GL_states()
# OpenGL code here...

Note that this function is quite expensive, as it saves all the possible OpenGL states and matrices, even the ones you don’t care about. Therefore it should be used wisely. It is provided for convenience, but the best results will be achieved if you handle OpenGL states yourself (because you know which states have really changed, and need to be saved and restored). Take a look at the reset_GL_states() function if you do so.

pop_GL_states()

Restore the previously saved OpenGL render states and matrices.

See the description of push_GL_states() to get a detailed description of these functions.

reset_GL_states()

Reset the internal OpenGL states so that the target is ready for drawing.

This function can be used when you mix pySFML drawing and direct OpenGL rendering, if you choose not to use push_GL_states()/pop_GL_states(). It makes sure that all OpenGL states needed by pySFML are set, so that subsequent draw() calls will work as expected.

# OpenGL code here... glPushAttrib(...) window.reset_GL_states() window.draw(...) window.draw(...) glPopAttrib(...) # OpenGL code here...

RenderWindow

class sfml.graphics.RenderWindow(sfml.graphics.Window, sfml.graphics.RenderTarget)

Window that can serve as a target for 2D drawing.

RenderWindow is the main class of the graphics module.

It defines an OS window that can be painted using the other classes of the graphics module.

RenderWindow is derived from Window, thus it inherits all its features: events, window management, OpenGL rendering, etc. See the documentation of Window for a more complete description of all these features, as well as code examples.

On top of that, RenderWindow adds more features related to 2D drawing with the graphics module (see its base class RenderTarget for more details). Here is a typical rendering and event loop with an RenderWindow

RenderWindow(mode, title[, style[, settings]])

Construct a new window.

This constructor creates the window with the size and pixel depth defined in mode. An optional style can be passed to customize the look and behaviour of the window (borders, title bar, resizable, closable, ...).

The fourth parameter is an optional structure specifying advanced OpenGL context settings such as antialiasing, depth-buffer bits, etc. You shouldn’t care about these parameters for a regular usage of the graphics module.

Parameters:
capture()

Copy the current contents of the window to an image.

This is a slow operation, whose main purpose is to make screenshots of the application. If you want to update an image with the contents of the window and then use it for drawing, you should rather use an Texture and its Texture.update_from_window() function. You can also draw things directly to a texture with the RenderTexture class.

Returns:Image containing the captured contents
Return type:sfml.graphics.Image

RenderTexture

class sfml.graphics.RenderTexture(sfml.graphics.RenderTarget)

Target for off-screen 2D rendering into an texture.

RenderTexture is the little brother of RenderWindow.

It implements the same 2D drawing and OpenGL-related functions (see their base class RenderTarget for more details), the difference is that the result is stored in an off-screen texture rather than being show in a window.

Rendering to a texture can be useful in a variety of situations:

  • precomputing a complex static texture (like a level’s background from multiple tiles)
  • applying post-effects to the whole scene with shaders
  • creating a sprite from a 3D object rendered with OpenGL
  • etc.

Usage example:

# create a new render-window
window = sf.RenderWindow(sf.VideoMode(800, 600), "pySFML - RenderWindow")

# create a new render-texture
texture = sf.RenderTexture.create(500, 500)

# the main loop
while window.is_open:

   # ...

   # clear the whole texture with red color
   texture.clear(sf.Color.RED)

   # draw stuff to the texture
   texture.draw(sprite)
   texture.draw(shape)
   texture.draw(text)

   # we're done drawing to the texture
   texture.display()

   # now we start rendering to the window, clear it first
   window.clear()

   # draw the texture
   sprite = sf.Sprite(texture.texture)
   window.draw(sprite)

   # end the current frame and display its content on screen
   window.display()
RenderTexture(width, height[, depth_buffer=False])

Construct the render-texture.

The last parameter, depth_buffer, is useful if you want to use the render-texture for 3D OpenGL rendering that requires a depth-buffer. Otherwise it is unnecessary, and you should leave this parameter to false (which is its default value).

Parameters:
  • width (integer) – Width of the render-texture
  • height (integer) – Height of the render-texture
  • depth_buffer (integer) – Do you want this render-texture to have a depth buffer?
Return type:

sfml.graphics.RenderTexture
smooth

Enable or disable texture smoothing.

This property is similar to Texture.smooth. This parameter is disabled by default.

Return type:bool
active

Activate of deactivate the render-texture for rendering.

This function makes the render-texture’s context current for future OpenGL rendering operations (so you shouldn’t care about it if you’re not doing direct OpenGL stuff). Only one context can be current in a thread, so if you want to draw OpenGL geometry to another render target (like an RenderWindow) don’t forget to activate it again.

Return type:bool
display()

Update the contents of the target texture.

This function updates the target texture with what has been drawn so far. Like for windows, calling this function is mandatory at the end of rendering. Not calling it may leave the texture in an undefined state.

texture

Get a read-only reference to the target texture.

After drawing to the render-texture and calling display(), you can retrieve the updated texture using this function, and draw it using a sprite (for example). The internal Texture of a render-texture is always the same instance, so that it is possible to call this function once and keep a reference to the texture even after it is modified.

Return type:sfml.graphics.Texture