# Graphics

- PrimitiveType

- Rectangle

- Color

- Transform

- BlendMode

- Pixels

- Image

- Texture

- Glyph

- Font

- Shader

- RenderStates

- Drawable

- Transformable

- Sprite

- Text

- Shape

- CircleShape

- ConvexShape

- RectangleShape

- Vertex

- VertexArray

- View

- RenderTarget

- RenderWindow

- RenderTexture

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

      - factor (`sfml.system.Vector2` or tuple) – Scaling factors

      - center (`sfml.system.Vector2` or tuple) – Center of scaling

    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:

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

  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

      - width (integer) – Width of the image

      - height (integer) – Height of the image

      - color (sfml.graphics.Color) – Fill color

    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

      - color (sfml.graphics.Color) – Color to make transparent

      - alpha (integer) – Alpha value to assign to transparent pixels

  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

      - filename (str) – Path of the image file to load

      - area (`sfml.graphics.Rectangle`) – Area of the image to load

    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

      - data (bytes) – Data to load

      - area (`sfml.graphics.Rectangle`) – Area of the image to load

    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

      - image (sfml.graphics.Image) – Image to load into the texture

      - area (sfml.graphics.Rectangle) – Area of the image to load

    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

      - pixels (sfml.graphics.Pixels) – Array of pixels to copy to the texture

      - position (sfml.system.Vector2) – Offset in the texture where to copy the source pixels

  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

      - image (sfml.graphics.Image) – Image to copy to the texture

      - position (sfml.system.Vector2) – Offset in the texture where to copy the source image

  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

      - window (sfml.window.Window) – Window to copy to the texture

      - position (sfml.system.Vector2) – Offset in the texture where to copy the source window

  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

      - name (str) – Name of the parameter in the shader

      - transform (sfml.graphics.Transform) – Transform to assign

  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

      - blendmode (`sfml.graphics.BlendMode`’s constant) – Blend mode to use

      - transform (sfml.graphics.Transform) – Transform to use

      - texture (sfml.graphics.Texture) – Texture to use

      - shader (sfml.graphics.Shader) – Shader to use

    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

      - target (sfml.graphics.RenderTarget) – Render target to draw to

      - states (sfml.graphics.RenderStates) – Current render states

## 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 (sfml.graphics.Texture) – Source texture

      - rectangle (sfml.graphics.Rectangle) – Sub-rectangle of the texture to assign to the sprite

  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 str

  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

      - index (integer) – Index of the point to change, in range [0 .. `point_count` - 1]

      - point (sfml.system.Vector2) – New position of the point

## 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 (sfml.system.Vector2) – `Vertex` position

      - color (sfml.graphics.Color) – `Vertex` color

      - tex_coords (sfml.system.Vector2) – `Vertex` texture coordinates

  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

      - type (sfml.graphics.PrimitiveType) – Type of primitives

      - vertex_count (integer) – Initial number of vertices in the array

  __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

      - point (sfml.system.Vector2) – Point to convert, relative to the render target

      - view (sfml.graphics.View) – The view to use for converting the point

    Returns

      The converted point, in “world” units

    Return type

      `sfml.system.Vector2`

  draw(drawable[, states])

    Draw a drawable object to the render-target.

    Parameters

      - drawable (sfml.graphics.Drawable) – Object to draw

      - states (sfml.graphics.RenderStates) – Render states to use for drawing

  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

      - mode (sfml.window.VideoMode) – Video mode to use (defines the width, height and depth of the rendering area of the window)

      - title (str) – Title of the window

      - style (`sfml.window.Style`’s constant) – Window style

      - settings (sfml.window.ContextSettings) – Additional settings for the underlying OpenGL context

  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`