Graphics ======== .. module:: sfml.graphics .. contents:: :local: PrimitiveType ^^^^^^^^^^^^^ .. py:class:: PrimitiveType Empty class that defines some constants. The are the types of primitives that an :class:`VertexArray` can render. :const:`POINTS` and :class:`LINES` have no area, therefore their thickness will always be 1 pixel, regardless of the current transform and view. .. py:data:: POINTS List of individual points. .. py:data:: LINES List of individual lines. .. py:data:: LINES_STRIP List of connected lines, a point uses the previous point to form a line. .. py:data:: TRIANGLES List of individual triangles. .. py:data:: TRIANGLES_STRIP List of connected triangles, a point uses the two previous points to form a triangle. .. py:data:: TRIANGLES_FAN List of connected triangles, a point uses the common center and the previous point to form a triangle. .. py:data:: QUADS List of individual quads. Rectangle ^^^^^^^^^ .. class:: 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 :class:`.Vector2`. Unlike SFML, :class:`Rectangle` does define functions to emulate the properties that are not directly members (such as right, bottom, center, etc.). :class:`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)) .. method:: Rectangle(position=(0, 0), size=(0, 0)) Construct an :class:`sfml.graphics.Rectangle` .. attribute:: position Top-left coordinate of the rectangle. .. attribute:: size Position of the rectangle. .. attribute:: left Left coordinate of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.x .. attribute:: top Top coordinate of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.y .. attribute:: width Width of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.size.width .. attribute:: height Height of the rectangle. This attribute is provided as a shortcut to sfml.graphics.Rectangle.position.height .. attribute:: center The center of the rectangle. .. attribute:: right The right coordinate of the rectangle. .. attribute:: bottom The bottom coordinate of the rectangle. .. method:: contains(point) Check if a point is inside the rectangle's area. :param sfml.system.Vector2 point: Point to test :rtype: bool .. method:: intersects(rectangle) Check the intersection between two rectangles. This overload returns the overlapped rectangle if an intersection is found. :param sfml.graphics.Rectangle rectangle: Rectangle to test :return: Rectangle filled with the intersection or None :rtype: :class:`sfml.graphics.Rectangle` or None Color ^^^^^ .. py:class:: Color Utility class for manipulating RGBA colors. :class:`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 \*. .. py:method:: Color([r=0[, g=0[, b=0[, a=255]]]]) Construct the color from its 4 RGBA components. :param integer r: Red component (in the range [0, 255]) :param integer g: Green component (in the range [0, 255]) :param integer b: Blue component (in the range [0, 255]) :param integer a: Alpha (opacity) component (in the range [0, 255]) .. py:data:: BLACK Black predefined color. .. py:data:: WHITE White predefined color. .. py:data:: RED Red predefined color. .. py:data:: GREEN Green predefined color. .. py:data:: BLUE Blue predefined color. .. py:data:: YELLOW Yellow predefined color. .. py:data:: MAGENTA Magenta predefined color. .. py:data:: CYAN Cyan predefined color. .. py:data:: TRANSPARENT Transparent (black) predefined color. .. py:attribute:: r Red component. .. py:attribute:: g Green component. .. py:attribute:: b Blue component. .. py:attribute:: a Alpha (opacity) component. Transform ^^^^^^^^^ .. py:class:: Transform Define a 3x3 transform matrix. A :class:`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))) .. py:classmethod:: from_values(a00, a01, a02, a10, a11, a12, a20, a21, a22) Construct a transform from a 3x3 matrix :param float a00: Element (0, 0) of the matrix :param float a01: Element (0, 1) of the matrix :param float a02: Element (0, 2) of the matrix :param float a10: Element (1, 0) of the matrix :param float a11: Element (1, 1) of the matrix :param float a12: Element (1, 2) of the matrix :param float a20: Element (2, 0) of the matrix :param float a21: Element (2, 1) of the matrix :param float a22: Element (2, 2) of the matrix :rtype: :class:`sfml.graphics.Transform` .. py:attribute:: 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 .. py:attribute:: inverse Return the inverse of the transform. If the inverse cannot be computed, an identity transform is returned. :type: :class:`sfml.graphics.Transform` .. py:method:: transform_point(point) Transform a 2D point. :param point: Point to transform :type point: :class:`sfml.system.Vector2` or tuple :return: Transformed point :rtype: :class:`sfml.system.Vector2` .. py:method:: 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. :param rectangle: Rectangle to transform :type rectangle: :class:`sfml.graphics.Rectangle` or tuple :return: Transformed rectangle :rtype: :class:`sfml.graphics.Rectangle` .. py:method:: 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. :param sfml.graphics.Rectangle transform: Transform to combine with this transform :return: Return itself :rtype: :class:`sfml.graphics.Transform` .. py:method:: 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) :param offset: Translation offset to apply :type offset: :class:`sfml.system.Vector2` or tuple :return: Return itself :rtype: :class:`sfml.graphics.Transform` .. py:method:: 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)) :param float angle: Rotation angle, in degrees :param center: Center of rotation :type center: :class:`sfml.system.Vector2` or tuple :return: Return itself :rtype: :class:`sfml.graphics.Transform` .. py:method:: 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) :param factor: Scaling factors :type factor: :class:`sfml.system.Vector2` or tuple :param center: Center of scaling :type center: :class:`sfml.system.Vector2` or tuple :return: Return itself :rtype: :class:`sfml.graphics.Transform` BlendMode ^^^^^^^^^ .. py:class:: BlendMode :class:`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 (:attr:`color_src_factor`) * Color Destination Factor (:attr:`color_dst_factor`) * Color Blend Equation (:attr:`color_equation`) * Alpha Source Factor (:attr:`alpha_src_factor`) * Alpha Destination Factor (:attr:`alpha_dst_factor`) * Alpha Blend Equation (:attr:`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 :class:`Drawable` object to a render target. It is part of the :class:`RenderStates` compound that is passed to the member function :meth:`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 | +----------+-------------------------------------------+ .. py:method:: BlendMode(*args, **kwargs): Construct the blend mode given the factors and equation. :param integer color_source_factor: Specifies how to compute the source factor for the color channels. :param integer color_destination_factor: Specifies how to compute the destination factor for the color channels. :param integer color_blend_equation: Specifies how to combine the source and destination colors. :param integer alpha_source_factor: Specifies how to compute the source factor. :param integer alpha_destination_factor: Specifies how to compute the destination factor. :param integer alpha_blend_equation: Specifies how to combine the source and destination alphas. .. py:attribute:: color_src_factor Source blending factor for the color channels .. py:attribute:: color_dst_factor Destination blending factor for the color channels .. py:attribute:: color_equation Blending equation for the color channels .. py:attribute:: alpha_src_factor Source blending factor for the alpha channel .. py:attribute:: alpha_dst_factor Destination blending factor for the alpha channel .. py:attribute:: alpha_equation Blending equation for the alpha channel .. py:data:: BLEND_ALPHA Blend source and dest according to dest alpha .. py:data:: BLEND_ADD Add source to dest .. py:data:: BLEND_MULTIPLY Multiply source and dest .. py:data:: BLEND_NONE Overwrite dest with source Pixels ^^^^^^ .. py:class:: Pixels .. py:attribute:: width .. py:attribute:: height .. py:attribute:: data Image ^^^^^ .. py:class:: Image Class for loading, manipulating and saving images. :class:`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. :class:`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 :class:`Color`. All the functions that return an array of pixels follow this rule, and all parameters that you pass to :class:`Image` functions (such as :func:`from_pixels`) must use this representation as well. A :class:`Image` can be copied, but it is a heavy resource; keep it in mind! For debugging purpose, you can call its method :meth:`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") .. py:classmethod:: create(width, height[, color]) Create the image and fill it with a unique color. :param integer width: Width of the image :param integer height: Height of the image :param sfml.graphics.Color color: Fill color :rtype: :class:`sfml.graphics.Image` .. py:classmethod:: from_pixels(pixels) Create the image from an array of pixels wrapped around :class:`Pixels`. This function fails without raising error if pixels are invalid. On the other hand, it raises one if *pixels* points on *NULL*? :raise: :exc:`sfml.system.SFMLException` - If *pixels* is empty. :param sfml.window.Pixels pixels: Array of pixels to copy to the image :rtype: :class:`sfml.graphics.Image` .. py: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: :exc:`IOError` - The image failed to load :param str filename: Path of the image file to load :rtype: :class:`sfml.graphics.Image` .. py: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: :exc:`IOError` - The image failed to load :param bytes data: The data to load, in bytes :rtype: :class:`sfml.graphics.Image` .. py: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: :exc:`IOError` - If the image is empty :param str filename: Path of the file to save .. py:method:: 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. .. py:attribute:: size Return the size of the image. :type: :class:`sfml.system.Vector2` .. py:attribute:: width Return the width of the image. :type: integer .. py:attribute:: height Return the width of the image. :type: height .. py:method:: 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. :param sfml.graphics.Color color: Color to make transparent :param integer alpha: Alpha value to assign to transparent pixels .. py:method:: 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 :class:`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. :param sfml.graphics.Image source: Source image to copy :param dest: Coordinate of the destination position :type dest: :class:`sfml.system.Vector2` or None :param source_rect: Sub-rectangle of the source image to copy :type source_rect: :class:`sfml.graphics.Rectangle` or tuple :param bool apply_alpha: Should the copy take in account the source transparency ? .. py:attribute:: pixels Get a read-only pointer to the array of pixels. This pointer is wrapped around :class:`Pixels`. The returned value points to an array of RGBA pixels made of 8 bits integers components. The size of the array is :attr:`width` * :attr:`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: :class:`sfml.window.Pixels` or None .. py:method:: flip_horizontally() Flip the image horizontally (left <-> right) .. py:method:: flip_vertically Flip the image vertically (top <-> bottom) .. py:method:: __getitem__() Get a pixel from the image. :: print(image[0,0]) # create tuple implicitly print(image[(0,0)]) # create tuple explicitly .. py:method:: __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 ^^^^^^^ .. py:class:: Texture :class:`Image` living on the graphics card that can be used for drawing. :class:`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 :class:`Image`, you need to prepare the pixels first and then upload them to the texture in a single operation (see :func:`Texture.update`). :class:`Texture` makes it easy to convert from/to :class:`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 :class:`Image`, do whatever you need with the pixels, and then call :func:`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 :class:`Image`, :class:`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 :class:`Color`. Usage example: This first example shows the most common use of :class:`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 :class:`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) # ... .. py:method:: Texture() The default constructor is not meant to be called. It will raise :exc:`NotImplementedError` with a message telling you that you must use a specific constructor. Those specific constructors are: :func:`create`, :func:`from_file`, :func:`from_memory`, :func:`from_image`. .. py:data:: NORMALIZED Texture coordinates in range [0 .. 1]. .. py:data:: PIXELS Texture coordinates in range [0 .. size]. .. py:classmethod:: create(width, height) Create a texture. :param integer width: Width of the texture :param integer height: Height of the texture :rtype: :class:`sfml.graphics.Texture` .. py: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 :class:`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 :func:`get_maximum_size` function. If this function fails, it raises an exception. :raise: :class:`IOError` - The texture failed to load :param str filename: Path of the image file to load :param area: Area of the image to load :type area: :class:`sfml.graphics.Rectangle` :rtype: :class:`sfml.graphics.Texture` .. py: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 :class:`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 :func:`get_maximum_size` function. If this function fails, it raises an exception. :raise: :class:`IOError` - The texture failed to load :param bytes data: Data to load :param area: Area of the image to load :type area: :class:`sfml.graphics.Rectangle` :rtype: :class:`sfml.graphics.Texture` .. py: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 :class:`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 :func:`get_maximum_size` function. If this function fails, it raises an error. :raise: :class:`sfml.system.SFMLException` - The texture failed to load :param sfml.graphics.Image image: Image to load into the texture :param sfml.graphics.Rectangle area: Area of the image to load :rtype: :class:`sfml.graphics.Texture` .. py:attribute:: size Return the size of the texture. :type: :class:`sfml.system.Vector2` .. py:attribute:: width Return the width of the texture. :type: integer .. py:attribute:: height Return the height of the texture. :type: integer .. py:method:: 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). :return: Image containing the texture's pixels :type: :class:`sfml.graphics.Image` .. py:method:: update(*args, **kwargs) Refer to :meth:`update_from_pixels`, :meth:`update_from_image` or :meth:`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. .. py:method:: 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. :param sfml.graphics.Pixels pixels: Array of pixels to copy to the texture :param sfml.system.Vector2 position: Offset in the texture where to copy the source pixels .. py:method:: 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. :param sfml.graphics.Image image: Image to copy to the texture :param sfml.system.Vector2 position: Offset in the texture where to copy the source image .. py:method:: 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. :param sfml.window.Window window: Window to copy to the texture :param sfml.system.Vector2 position: Offset in the texture where to copy the source window .. py:method:: 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 :class:`Texture` together with OpenGL code (this function is equivalent to glBindTexture). The coordinateType argument controls how texture coordinates will be interpreted. If :const:`NORMALIZED` (the default), they must be in range [0 .. 1], which is the default way of handling texture coordinates with OpenGL. If :const:`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. :param coordinate_type: Type of texture coordinates to use :type coordinate_type: :class:`sfml.graphics.Texture`'s constant .. py:attribute:: 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 .. py:attribute:: 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 .. py: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. :return: Maximum size allowed for textures, in pixels :rtype: integer Glyph ^^^^^ .. py:class:: Glyph Structure describing a glyph. A glyph is the visual representation of a character. The :class:`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 .. py:method:: Glyph() Default constructor. :rtype: :class:`sfml.graphics.Glyph` .. py:attribute:: advance Offset to move horizontally to the next character. :rtype: integer .. py:attribute:: bounds Bounding rectangle of the glyph, in coordinates relative to the baseline. :rtype: :class:`sfml.graphics.Rectangle` .. py:attribute:: texture_rectangle :class:`Texture` coordinates of the glyph inside the font's texture. :rtype: :class:`sfml.graphics.Rectangle` Font ^^^^ .. py:class:: 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 :func:`from_file` function for the complete list of supported formats. Once it is loaded, an :class:`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 :class:`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 :class:`Font` is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, an :class:`Text` is a lightweight object which can combine the glyphs data and metrics of an :class:`Font` to display any text on a render target. Note that it is also possible to bind several :class:`Text` instances to the same :class:`Font`. It is important to note that the :class:`Text` instance doesn't copy the font that it uses, it only keeps a reference to it. Thus, an :class:`Font` must not be destructed while it is used by an :class:`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 :class:`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. .. py:method:: Font() The default constructor is not meant to be called. It will raise :exc:`NotImplementedError` with a message telling you that you must use a specific constructor. Those specific constructors are: :func:`from_file` and :func:`from_memory`. .. py: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: :exc:`IOError` - The font failed to load :param str filename: Path of the font file to load :rtype: :class:`sfml.graphics.Font` .. py: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: :exc:`IOError` - The font failed to load :param bytes data: The data to load :rtype: :class:`sfml.graphics.Font` .. py:method:: get_glyph(code_point, character_size, bold) Retrieve a glyph of the font. :param integer code_point: Unicode code point of the character to get :param integer character_size: Reference character size :param bool bold: Retrieve the bold version or the regular one ? :return: The glyph corresponding to *code_point* and *character_size* :rtype: :class:`sfml.graphics.Glyph` .. py:method:: 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. :param integer first: Unicode code point of the first character :param integer second: Unicode code point of the second character :param integer character_size: Reference character size :return: Kerning value for first and second, in pixels :rtype: integer .. py:method:: get_line_spacing(character_size) Get the line spacing. Line spacing is the vertical offset to apply between two consecutive lines of text. :param integer character_size: Reference character size :return: Line spacing, in pixels :rtype: integer .. py:method:: 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 :class:`Text`. :param integer character_size: Reference character size :return: Texture containing the glyphs of the requested size :rtype: :class:`sfml.graphics.Texture` .. py:attribute:: info Various information about a font. :return: A string containing the font family :rtype: str Shader ^^^^^^ .. py:class:: Shader :class:`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 :class:`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. :class:`Shader` handles 4 different types of variables: * floats * vectors (2, 3 or 4 components) * textures * transforms (matrices) .. py:method:: Shader() The default constructor is not meant to be called. It will raise :exc:`NotImplementedError` with a message telling you that you must use a specific constructor. Those specific constructors are: :func:`from_file` and :func:`from_memory`. .. py: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: :exc:`IOError` - If one of the two shaders failed to load :param str vertex_filename: Path of the vertex or fragment shader file to load :param str fragment_filename: Path of the fragment shader file to load :rtype: :class:`sfml.graphics.Shader` .. py: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 :exc:`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: :exc:`IOError` - If one of the two shaders failed to load :param str vertex_shader: String containing the source code of the vertex shader :param str fragment_shader: String containing the source code of the fragment shader :rtype: :class:`sfml.graphics.Shader` .. py:method:: set_parameter(*args, **kwargs) This method takes care of calling the suitable set_parameter method. See the table below: +--------------------+------------------------------------------+ | Parameters | Method | +====================+==========================================+ | 1 float | :meth:`set_1float_parameter` | +--------------------+------------------------------------------+ | 2 float | :meth:`set_2float_parameter` | +--------------------+------------------------------------------+ | 3 float | :meth:`set_3float_parameter` | +--------------------+------------------------------------------+ | 4 float | :meth:`set_4float_parameter` | +--------------------+------------------------------------------+ | :class:`.Vector2` | :meth:`set_vector2_parameter` | +--------------------+------------------------------------------+ | :class:`.Vector3` | :meth:`set_vector3_parameter` | +--------------------+------------------------------------------+ | :class:`.Color` | :meth:`set_color_parameter` | +--------------------+------------------------------------------+ | :class:`Transform` | :meth:`set_transform_parameter` | +--------------------+------------------------------------------+ | :class:`Texture` | :meth:`set_texture_parameter` | +--------------------+------------------------------------------+ | CURRENT_TEXTURE | :meth:`set_currenttexturetype_parameter` | +--------------------+------------------------------------------+ .. py:method:: 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 :param str name: Name of the parameter in the shader :param float x: Value to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param float x: First component of the value to assign :param float y: Second component of the value to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param float x: First component of the value to assign :param float y: Second component of the value to assign :param float z: Third component of the value to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param float x: First component of the value to assign :param float y: Second component of the value to assign :param float z: Third component of the value to assign :param float w: Fourth component of the value to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param sfml.system.Vector2 vector: Vector to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param sfml.system.Vector3 vector: Vector to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param sfml.graphics.Color color: Color to assign .. py:method:: 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 :param str name: Name of the parameter in the shader :param sfml.graphics.Transform transform: Transform to assign .. py:method:: 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 :meth:`set_currenttexturetype_parameter`. :param str name: Name of the parameter in the shader :param sfml.graphics.Texture texture: Texture to assign .. py:method:: 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 .. py: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 ^^^^^^^^^^^^ .. py:class:: RenderStates Define the states used for drawing to a :class:`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 :class:`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 :class:`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. .. py:method:: RenderStates(blendmode=BLEND_ALPHA[, transform, [texture[, shader]]]) Construct a default render states with custom values. :param blendmode: Blend mode to use :type blendmode: :class:`sfml.graphics.BlendMode`'s constant :param sfml.graphics.Transform transform: Transform to use :param sfml.graphics.Texture texture: Texture to use :param sfml.graphics.Shader shader: Shader to use :rtype: :class:`sfml.graphics.RenderStates` .. py:data:: DEFAULT Special instance holding the default render states. .. py:attribute:: blendmode Blending mode. .. py:attribute:: transform Transform. .. py:attribute:: texture Texture. .. py:attribute:: shader Shader. Drawable ^^^^^^^^ .. py:class:: Drawable Abstract base class for objects that can be drawn to a render target. :class:`Drawable` is a very simple base class that allows objects of derived classes to be drawn to an :class:`RenderTarget`. All you have to do in your derived class is to override the draw virtual function. Note that inheriting from :class:`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() .. py:method:: 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. :param sfml.graphics.RenderTarget target: Render target to draw to :param sfml.graphics.RenderStates states: Current render states Transformable ^^^^^^^^^^^^^ .. py:class:: Transformable Decomposed transform defined by a position, a rotation and a scale. This class is provided for convenience, on top of :class:`Transform`. :class:`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 :class:`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 :class:`Transform`), and keeps it up-to-date. In addition to the position, rotation and scale, :class:`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 :class:`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 :class:`Transform` directly. :class:`Transformable` can be used as a base class. It is often combined with :class:`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) .. py:method:: Transformable() Default constructor. :rtype: :class:`sfml.graphics.Transformable` .. py:attribute:: position Set/get the position of the object This attribute completely overwrites the previous position. See :func:`move` to apply an offset based on the previous position instead. The default position of a transformable object is (0, 0). :rtype: :class:`sfml.system.Vector2` .. py:attribute:: rotation Set/get the orientation of the object This attribute completely overwrites the previous rotation. See :func:`rotate` to add an angle based on the previous rotation instead. The default rotation of a transformable object is 0. :rtype: float .. py:attribute:: ratio Set/get the scale factors of the object This function completely overwrites the previous ratio. See :func:`scale` to add a factor based on the previous scale instead. The default scale of a transformable object is (1, 1). :rtype: :class:`sfml.system.Vector2` .. py:attribute:: 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). :rtype: :class:`sfml.system.Vector2` .. py:method:: move(offset) Move the object by a given offset. This function adds to the current position of the object, unlike :attr:`position` which overwrites it. Thus, it is equivalent to the following code:: object.position = object.position + offset :param sfml.system.Vector2 offset: Offset .. py:method:: rotate(angle) Rotate the object. This function adds to the current rotation of the object, unlike :attr:`rotation` which overwrites it. Thus, it is equivalent to the following code:: object.rotation = object.rotation + angle .. py:method:: scale(factor) Scale the object. This function multiplies the current scale of the object, unlike :attr:`ratio` which overwrites it. Thus, it is equivalent to the following code:: object.ratio = object.ratio * factor .. py:attribute:: transform Get the combined transform of the object. :rtype: :class:`sfml.graphics.Transform` .. py:attribute:: inverse_transform Get the inverse of the combined transform of the object. :rtype: :class:`sfml.graphics.Transform` Sprite ^^^^^^ .. py:class:: Sprite(sfml.graphics.Drawable, sfml.graphics.Transformable) :class:`Drawable` representation of a texture, with its own transformations, color, etc. :class:`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 :class:`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. :class:`Sprite` works in combination with the :class:`Texture` class, which loads and provides the pixel data of a given texture. The separation of :class:`Sprite` and :class:`Texture` allows more flexibility and better performances: indeed a :class:`Texture` is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, an :class:`Sprite` is a lightweight object which can use the pixel data of an :class:`Texture` and draw it with its own transformation/color/blending attributes. It is important to note that the :class:`Sprite` instance doesn't copy the texture that it uses, it only keeps a reference to it. Thus, an :class:`Texture` must not be destroyed while it is used by an :class:`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) .. py:method:: Sprite(texture[, rectangle]) Construct the sprite from (a sub-rectangle of) a source texture. :param sfml.graphics.Texture texture: Source texture :param sfml.graphics.Rectangle rectangle: Sub-rectangle of the texture to assign to the sprite .. py:attribute:: 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 :attr:`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. :rtype: :class:`sfml.graphics.Texture` .. py:attribute:: 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. .. py:attribute:: 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. .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` Text ^^^^ .. py:class:: Text(sfml.graphics.Drawable, sfml.graphics.Transformable) Graphical text that can be drawn to a render target. :class:`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 :class:`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. :class:`Text` works in combination with the :class:`Font` class, which loads and provides the glyphs (visual characters) of a given font. The separation of :class:`Font` and :class:`Text` allows more flexibility and better performances: indeed a :class:`Font` is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a :class:`Text` is a lightweight object which can combine the glyphs data and metrics of an :class:`Font` to display any text on a render target. It is important to note that the :class:`Text` instance doesn't copy the font that it uses, it only keeps a reference to it. Thus, an :class:`Font` must not be destructed while it is used by an :class:`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 | +----------------+------------------------------+ .. py:method:: Text([string[, font[, character_size=30]]]) Construct the string, and optionally from a string, font and size. :param str: Text assigned to the string :type string: bytes or string :param sfml.graphics.Font font: Font used to draw the string :param integer character_size: Base size of characters, in pixels .. py:data:: REGULAR Regular characters, no style. .. py:data:: BOLD Bold characters. .. py:data:: ITALIC Italic characters. .. py:data:: UNDERLINED Underlined characters. .. py:data:: STRIKE_THROUGH Strike through characters. .. py:attribute:: string Set/get the text's string. :rtype: bytes or string .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Font` .. py:attribute:: character_size Set/get the character size. The default size is 30. :rtype: integer .. py:attribute:: 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 :data:`REGULAR`. :rtype: integer .. py:attribute:: color Set/get the global color of the text. By default, the text's color is opaque white. :rtype: :class:`sfml.graphics.Color` .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` .. py:method:: 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. :param integer index: Index of the character :return: Position of the character :rtype: :class:`sfml.system.Vector2` Shape ^^^^^ .. py:class:: Shape(sfml.graphics.Drawable, sfml.graphics.Transformable) Base class for textured shapes with outline. :class:`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 :const:`Color.TRANSPARENT` * the outline thickness can be zero .. py:method:: Shape() Shape is abstract, it would raise an error :exc:`NotImplementedError` .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Texture` or None .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` .. py:attribute:: 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 :const:`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. :rtype: :class:`sfml.graphics.Color` .. py:attribute:: outline_color Set/get the outline color of the shape. You can use :const:`Color.TRANSPARENT` to disable the outline. By default, the shape's outline color is opaque white. :rtype: :class:`sfml.graphics.Color` .. py:attribute:: 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. :rtype: float .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` .. py:attribute:: 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. :rtype: :class:`sfml.graphics.Rectangle` CircleShape ^^^^^^^^^^^ .. py:class:: CircleShape(sfml.graphics.Shape) Specialized shape representing a circle. This class inherits all the functions of :class:`Transformable` (position, rotation, scale, bounds, ...) as well as the functions of :class:`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 :class:`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, ... .. py:method:: CircleShape([radius[, point_count]) Default constructor. :param float radius: Radius of the circle :param integer point_count: Number of points composing the circle .. py:attribute:: radius Set/get the radius of the circle. :rtype: float .. py:attribute:: point_count Set/get the number of points of the circle. :rtype: integer .. py:method:: get_point(index) Get a point of the shape. The result is undefined if index is out of the valid range. :param integer index: Index of the point to get, in range [0 .. :attr:`point_count` - 1] :return: Index-th point of the shape :rtype: :class:`sfml.system.Vector2` ConvexShape ^^^^^^^^^^^ .. py:class:: ConvexShape(sfml.graphics.Shape) Specialized shape representing a convex polygon. This class inherits all the functions of :class:`Transformable` (position, rotation, scale, bounds, ...) as well as the functions of :class:`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) .. py:method:: ConvexShape() Default constructor. .. py:attribute:: point_count Set/get the number of points of the polygon. *count* must be greater than 2 to define a valid shape. :rtype: integer .. py:method:: get_point(index) Get the position of a point. The result is undefined if index is out of the valid range. :param integer index: Index of the point to get, in range [0 .. :attr:`point_count` - 1] :return: Vector2 of the index-th point of the polygon :rtype: :class:`sfml.system.Vector2` .. py:method:: 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! :attr:`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. :param integer index: Index of the point to change, in range [0 .. :attr:`point_count` - 1] :param sfml.system.Vector2 point: New position of the point RectangleShape ^^^^^^^^^^^^^^ .. py:class:: RectangleShape(sfml.graphics.Shape) Specialized shape representing a rectangle. This class inherits all the functions of :class:`Transformable` (position, rotation, scale, bounds, ...) as well as the functions of :class:`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) .. py:method:: RectangleShape([size]) Default constructor. :param sfml.system.Vector2 size: Size of the rectangle .. py:attribute:: size Set/get the size of the rectangle. :rtype: :class:`sfml.system.Vector2` .. py:attribute:: point_count Get the number of points defining the shape. :rtype: integer .. py:method:: get_point(index) Get the position of a point. The result is undefined if *index* is out of the valid range. :param integer index: Index of the point to get, in range [0 .. :attr:`point_count` - 1] :return: Vector2 of the index-th point of the shape :rtype: :class:`sfml.system.Vector2` Vertex ^^^^^^ .. py:class:: 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. .. py:method:: Vertex([position[, color[, tex_coords]]]) Construct the vertex from its position, color and texture coordinates. :param sfml.system.Vector2 position: :class:`Vertex` position :param sfml.graphics.Color color: :class:`Vertex` color :param sfml.system.Vector2 tex_coords: :class:`Vertex` texture coordinates .. py:attribute:: position 2D position of the vertex :rtype: :class:`sfml.system.Vector2` .. py:attribute:: color Color of the vertex. :rtype: :class:`sfml.graphics.Color` .. py:attribute:: tex_coords Coordinates of the texture's pixel to map to the vertex. :rtype: :class:`sfml.system.Vector2` VertexArray ^^^^^^^^^^^ .. py:class:: VertexArray(sfml.graphics.Drawable) Define a set of one or more 2D primitives. :class:`VertexArray` is a very simple wrapper around a dynamic array of vertices and a primitives type. It inherits :class:`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) .. py:method:: VertexArray([type[, vertex_count]]) Construct the vertex array with a type and an initial number of vertices. :param sfml.graphics.PrimitiveType type: Type of primitives :param integer vertex_count: Initial number of vertices in the array .. py:method:: __len__() Return the vertex count. .. py:method:: __getitem__(index) Get an access to a vertex by its index. .. py:method:: __setitem__(index, vertex) Set a vertex by its index. .. py:method:: 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. .. py:method:: 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. .. py:method:: append() Add a vertex to the array. .. py:attribute:: 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 :const:`POINTS`. :rtype: :class:`sfml.graphics.PrimitiveType` .. py:attribute:: bounds Compute the bounding rectangle of the vertex array. This returns the axis-aligned rectangle that contains all the vertices of the array. :rtype: :class:`sfml.graphics.Rectangle` View ^^^^ .. class:: View 2D camera that defines what region is shown on screen :class:`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) .. method:: View([rectangle]) Construct the view, and optionally from a rectangle. :param sfml.graphics.Rectangle rectangle: Rectangle defining the zone to display .. attribute:: center Set/get the center of the view. :rtype: :class:`sfml.system.Vector2` .. attribute:: size Set/get the size of the view. :rtype: :class:`sfml.system.Vector2` .. attribute:: rotation Set/get the orientation of the view. The default rotation of a view is 0 degree. :rtype: float .. attribute:: 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 :class:`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. .. method:: reset(rectangle) Reset the view to the given rectangle. Note that this function resets the rotation angle to 0. :param sfml.graphics.Rectangle rectangle: Rectangle defining the zone to display .. method:: move(offset) Move the view relatively to its current position. :param sfml.system.Vector2 offset: Move offset .. method:: rotate(angle) Rotate the view relatively to its current orientation. :param float angle: Angle to rotate, in degrees .. method:: 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) :param float factor: Zoom factor to apply .. attribute:: transform Get the projection transform of the view. This function is meant for internal use only. :return: Projection transform defining the view :rtype: :class:`sfml.graphics.Transform` .. attribute:: inverse_transform Get the inverse projection transform of the view. This function is meant for internal use only. :return: Inverse of the projection transform defining the view :rtype: :class:`sfml.graphics.Transform` RenderTarget ^^^^^^^^^^^^ .. py:class:: RenderTarget Base class for all render targets (window, texture, ...) :class:`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 :class:`RenderTarget` is also able to use views (:class:`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 :class:`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 :func:`push_GL_states`/:func:`pop_GL_states` functions. .. py:method:: RenderTarget() This class is abstract. .. py:method:: 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. :param sfml.graphics.Color color: Fill color to use to clear the render target .. py:attribute:: 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 :attr:`default_view` to this attribute. :rtype: :class:`sfml.graphics.View` .. py:attribute:: 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. .. py:method:: 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. :param sfml.graphics.View view: The view for which we want to compute the viewport :return: Viewport rectangle, expressed in pixels :rtype: :class:`sfml.graphics.Rectangle` .. py:method:: 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. :param sfml.system.Vector2 point: Point to convert, relative to the render target :param sfml.graphics.View view: The view to use for converting the point :return: The converted point, in "world" units :rtype: :class:`sfml.system.Vector2` .. py:method:: draw(drawable[, states]) Draw a drawable object to the render-target. :param sfml.graphics.Drawable drawable: Object to draw :param sfml.graphics.RenderStates states: Render states to use for drawing .. py:attribute:: size Return the size of the rendering region of the target. :rtype: :class:`sfml.system.Vector2` .. py:attribute:: width Return the width of the rendering region of the target. :rtype: integer .. py:attribute:: height Return the height of the rendering region of the target. :rtype: integer .. py:method:: 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 :func:`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 :func:`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 :func:`reset_GL_states` function if you do so. .. py:method:: pop_GL_states() Restore the previously saved OpenGL render states and matrices. See the description of :func:`push_GL_states` to get a detailed description of these functions. .. py:method:: 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 :func:`push_GL_states`/:func:`pop_GL_states`. It makes sure that all OpenGL states needed by pySFML are set, so that subsequent :func:`draw` calls will work as expected. # OpenGL code here... glPushAttrib(...) window.reset_GL_states() window.draw(...) window.draw(...) glPopAttrib(...) # OpenGL code here... RenderWindow ^^^^^^^^^^^^ .. py:class:: RenderWindow(sfml.graphics.Window, sfml.graphics.RenderTarget) :class:`.Window` that can serve as a target for 2D drawing. :class:`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. :class:`RenderWindow` is derived from :class:`.Window`, thus it inherits all its features: events, window management, OpenGL rendering, etc. See the documentation of :class:`.Window` for a more complete description of all these features, as well as code examples. On top of that, :class:`RenderWindow` adds more features related to 2D drawing with the graphics module (see its base class :class:`RenderTarget` for more details). Here is a typical rendering and event loop with an :class:`RenderWindow` .. py:method:: 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. :param sfml.window.VideoMode mode: Video mode to use (defines the width, height and depth of the rendering area of the window) :param str title: Title of the window :param style: Window style :type style: :class:`sfml.window.Style`'s constant :param sfml.window.ContextSettings settings: Additional settings for the underlying OpenGL context .. py:method:: 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 :class:`Texture` and its :func:`Texture.update_from_window` function. You can also draw things directly to a texture with the :class:`RenderTexture` class. :return: Image containing the captured contents :rtype: :class:`sfml.graphics.Image` RenderTexture ^^^^^^^^^^^^^ .. py:class:: RenderTexture(sfml.graphics.RenderTarget) Target for off-screen 2D rendering into an texture. :class:`RenderTexture` is the little brother of :class:`RenderWindow`. It implements the same 2D drawing and OpenGL-related functions (see their base class :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() .. py:method:: 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). :param integer width: Width of the render-texture :param integer height: Height of the render-texture :param integer depth_buffer: Do you want this render-texture to have a depth buffer? :rtype: :class:`sfml.graphics.RenderTexture` .. py:attribute:: smooth Enable or disable texture smoothing. This property is similar to :attr:`Texture.smooth`. This parameter is disabled by default. :rtype: bool .. py:attribute:: 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 :class:`RenderWindow`) don't forget to activate it again. :rtype: bool .. py:method:: 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. .. py:attribute:: texture Get a read-only reference to the target texture. After drawing to the render-texture and calling :func:`display`, you can retrieve the updated texture using this function, and draw it using a sprite (for example). The internal :class:`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. :rtype: :class:`sfml.graphics.Texture`