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.
List of individual points.
List of individual lines.
List of connected lines, a point uses the previous point to form a line.
List of individual triangles.
List of connected triangles, a point uses the two previous points to form a triangle.
List of connected triangles, a point uses the common center and the previous point to form a triangle.
List of individual quads.
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))
Construct an sfml.graphics.Rectangle
Top-left coordinate of the rectangle.
Position of the rectangle.
Left coordinate of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.x
Top coordinate of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.y
Width of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.size.width
Height of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.height
The center of the rectangle.
The right coordinate of the rectangle.
The bottom coordinate of the rectangle.
Check if a point is inside the rectangle’s area.
Parameters: | point (sfml.system.Vector2) – Point to test |
---|---|
Return type: | bool |
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 |
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 blueThe 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.TRANSPARENTColors can also be added and modulated (multiplied) using the overloaded operators + and *.
Construct the color from its 4 RGBA components.
Parameters: |
|
---|
Black predefined color.
White predefined color.
Red predefined color.
Green predefined color.
Blue predefined color.
Yellow predefined color.
Magenta predefined color.
Cyan predefined color.
Transparent (black) predefined color.
Red component.
Green component.
Blue component.
Alpha (opacity) component.
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)))
Construct a transform from a 3x3 matrix
Parameters: |
|
---|---|
Return type: |
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 |
---|
Return the inverse of the transform.
If the inverse cannot be computed, an identity transform is returned.
Type: | sfml.graphics.Transform |
---|
Transform a 2D point.
Parameters: | point (sfml.system.Vector2 or tuple) – Point to transform |
---|---|
Returns: | Transformed point |
Return type: | sfml.system.Vector2 |
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 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 |
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 |
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: |
|
---|---|
Returns: | Return itself |
Return type: |
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: |
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:
- Color Source Factor (color_src_factor)
- Color Destination Factor (color_dst_factor)
- Color Blend Equation (color_equation)
- Alpha Source Factor (alpha_src_factor)
- Alpha Destination Factor (alpha_dst_factor)
- Alpha Blend Equation (alpha_equation)
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 |
Construct the blend mode given the factors and equation.
Parameters: |
|
---|
Source blending factor for the color channels
Destination blending factor for the color channels
Blending equation for the color channels
Source blending factor for the alpha channel
Destination blending factor for the alpha channel
Blending equation for the alpha channel
Blend source and dest according to dest alpha
Add source to dest
Multiply source and dest
Overwrite dest with source
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")
Create the image and fill it with a unique color.
Parameters: |
|
---|---|
Return type: |
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 |
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 |
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 |
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 |
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.
Return the size of the image.
Type: | sfml.system.Vector2 |
---|
Return the width of the image.
Type: | integer |
---|
Return the width of the image.
Type: | height |
---|
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: |
|
---|
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: |
|
---|
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 the image horizontally (left <-> right)
Flip the image vertically (top <-> bottom)
Get a pixel from the image.
print(image[0,0]) # create tuple implicitly
print(image[(0,0)]) # create tuple explicitly
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
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)
# ...
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().
Texture coordinates in range [0 .. 1].
Texture coordinates in range [0 .. size].
Create a texture.
Parameters: |
|
---|---|
Return type: |
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: |
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: |
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: |
Return the size of the texture.
Type: | sfml.system.Vector2 |
---|
Return the width of the texture.
Type: | integer |
---|
Return the height of the texture.
Type: | integer |
---|
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 |
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 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 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 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: |
|
---|
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 |
---|
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 |
---|
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 |
---|
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 |
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
Default constructor.
Return type: | sfml.graphics.Glyph |
---|
Offset to move horizontally to the next character.
Return type: | integer |
---|
Bounding rectangle of the glyph, in coordinates relative to the baseline.
Return type: | sfml.graphics.Rectangle |
---|
Texture coordinates of the glyph inside the font’s texture.
Return type: | sfml.graphics.Rectangle |
---|
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.ITALICApart 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.
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().
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 |
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 |
Retrieve a glyph of the font.
Parameters: |
|
---|---|
Returns: | The glyph corresponding to code_point and character_size |
Return type: |
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: |
|
---|---|
Returns: | Kerning value for first and second, in pixels |
Return type: | integer |
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 |
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 |
Various information about a font.
Returns: | A string containing the font family |
---|---|
Return type: | str |
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)
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().
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: |
|
Return type: |
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: |
|
Return type: |
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() |
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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: |
|
---|
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 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()
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.
Construct a default render states with custom values.
Parameters: |
|
---|---|
Return type: |
Special instance holding the default render states.
Blending mode.
Transform.
Texture.
Shader.
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 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: |
|
---|
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)
Default constructor.
Return type: | sfml.graphics.Transformable |
---|
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 |
---|
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 |
---|
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 |
---|
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 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 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 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
Get the combined transform of the object.
Return type: | sfml.graphics.Transform |
---|
Get the inverse of the combined transform of the object.
Return type: | sfml.graphics.Transform |
---|
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)
Construct the sprite from (a sub-rectangle of) a source texture.
Parameters: |
|
---|
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 |
---|
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.
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.
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 |
---|
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 |
---|
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
Construct the string, and optionally from a string, font and size.
Parameters: |
|
---|
Regular characters, no style.
Bold characters.
Italic characters.
Underlined characters.
Strike through characters.
Set/get the text’s string.
Return type: | bytes or string |
---|
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 |
---|
Set/get the character size.
The default size is 30.
Return type: | integer |
---|
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 |
---|
Set/get the global color of the text.
By default, the text’s color is opaque white.
Return type: | sfml.graphics.Color |
---|
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 |
---|
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 |
---|
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 |
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 is abstract, it would raise an error NotImplementedError
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 |
---|
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 |
---|
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 |
---|
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 |
---|
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 |
---|
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 |
---|
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 |
---|
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, ...
Default constructor.
Parameters: |
|
---|
Set/get the radius of the circle.
Return type: | float |
---|
Set/get the number of points of the circle.
Return type: | integer |
---|
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 |
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)
Default constructor.
Set/get the number of points of the polygon.
count must be greater than 2 to define a valid shape.
Return type: | integer |
---|
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 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: |
|
---|
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)
Default constructor.
Parameters: | size (sfml.system.Vector2) – Size of the rectangle |
---|
Set/get the size of the rectangle.
Return type: | sfml.system.Vector2 |
---|
Get the number of points defining the shape.
Return type: | integer |
---|
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 |
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.
Construct the vertex from its position, color and texture coordinates.
Parameters: |
|
---|
2D position of the vertex
Return type: | sfml.system.Vector2 |
---|
Color of the vertex.
Return type: | sfml.graphics.Color |
---|
Coordinates of the texture’s pixel to map to the vertex.
Return type: | sfml.system.Vector2 |
---|
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)
Construct the vertex array with a type and an initial number of vertices.
Parameters: |
|
---|
Return the vertex count.
Get an access to a vertex by its index.
Set a vertex by its index.
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 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.
Add a vertex to the array.
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 |
---|
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 |
---|
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)
Construct the view, and optionally from a rectangle.
Parameters: | rectangle (sfml.graphics.Rectangle) – Rectangle defining the zone to display |
---|
Set/get the center of the view.
Return type: | sfml.system.Vector2 |
---|
Set/get the size of the view.
Return type: | sfml.system.Vector2 |
---|
Set/get the orientation of the view.
The default rotation of a view is 0 degree.
Return type: | float |
---|
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 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 the view relatively to its current position.
Parameters: | offset (sfml.system.Vector2) – Move offset |
---|
Rotate the view relatively to its current orientation.
Parameters: | angle (float) – Angle to rotate, in degrees |
---|
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 |
---|
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 |
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 |
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.
This class is abstract.
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 |
---|
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 |
---|
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 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 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: |
Draw a drawable object to the render-target.
Parameters: |
|
---|
Return the size of the rendering region of the target.
Return type: | sfml.system.Vector2 |
---|
Return the width of the rendering region of the target.
Return type: | integer |
---|
Return the height of the rendering region of the target.
Return type: | integer |
---|
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.
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 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...
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
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: |
|
---|
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 |
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()
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: |
|
---|---|
Return type: |
Enable or disable texture smoothing.
This property is similar to Texture.smooth. This parameter is disabled by default.
Return type: | bool |
---|
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 |
---|
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.
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 |
---|