Class OcsfmlGraphics.texture

class texture : ?rect:IntRect.t -> [ `Copy of < rep__sf_Texture : Texture.t; .. >
| `File of string
| `Image of image
| `Memory of OcsfmlSystem.raw_data_type
| `None
| `Stream of OcsfmlSystem.input_stream ] ->
object .. end
Image living on the graphics card that can be used for drawing.

texture stores pixels that can be drawn, with a sprite for example.

A texture lives in the graphics card memory, therefore it is very fast to draw a texture to a render target, or copy a render target to a texture (the graphics card can access both directly).

Being stored in the graphics card memory has some drawbacks. A texture cannot be manipulated as freely as a image, you need to prepare the pixels first and then upload them to the texture in a single operation (see texture#update ).

texture makes it easy to convert from/to image, but keep in mind that these calls require transfers between the graphics card and the central memory, therefore they are slow operations.

A texture can be loaded from an image, but also directly from a file/memory/stream. 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 a image, do whatever you need with the pixels, and then call texture#load_from_image.

Since they live in the graphics card memory, the pixels of a texture cannot be accessed without a slow copy first. And they cannot be accessed individually. Therefore, if you need to read the texture's pixels (like for pixel-perfect collisions), it is recommended to store the collision information separately, for example in an array of booleans.

Like image, texture can handle a unique internal representation of pixels, which is RGBA 32 bits. This means that a pixel must be composed of 8 bits red, green, blue and alpha channels -- just like a color.


method affect : 'a. (#const_texture as 'a) -> unit
method copy_to_image : 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).

method create : int -> int -> unit
Create the texture.

If this function fails, the texture is left unchanged.

method destroy : unit
method get_size : int * int
Return the size of the texture.
Returns Size in pixels.
method is_repeated : bool
Tell whether the texture is repeated or not.
Returns True if repeat mode is enabled, false if it is disabled.
method is_smooth : bool
Tell whether the smooth filter is enabled or not.
Returns True if smoothing is enabled, false if it is disabled.
method load_from_file : ?rect:IntRect.t -> string -> bool
Load the texture from a file on disk.

The rect 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. 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 getMaximumSize function.

If this function fails, the texture is left unchanged.
Returns True if loading was successful.

rect : Area of the image to load.
method load_from_image : ?rect:IntRect.t -> image -> bool
Load the texture from an image.

The rect 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. 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 OcsfmlGraphics.get_maximum_texture_size function.

If this function fails, the texture is left unchanged.
Returns True if loading was successful.

rect : Area of the image to load.
method load_from_memory : ?rect:IntRect.t -> OcsfmlSystem.raw_data_type -> bool
method load_from_stream : ?rect:IntRect.t -> OcsfmlSystem.input_stream -> bool
Load the texture from a custom stream.

The rect 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. 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 OcsfmlGraphics.get_maximum_texture_size function.

If this function fails, the texture is left unchanged.
Returns True if loading was successful.

rect : Area of the image to load.
method set_repeated : bool -> unit
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.

method set_smooth : bool -> unit
Enable or disable 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.

method update_from_image : ?coords:int * int -> image -> unit
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. The other overload, which has (x, y) additional arguments, is more convenient 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.

coords : Offset in the texture where to copy the source image.
method update_from_pixels : ?coords:int * int -> OcsfmlWindow.pixel_array_type -> unit
method update_from_window : 'b. ?coords:int * int -> (#OcsfmlWindow.window as 'b) -> unit
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. The other overload, which has (x, y) additional arguments, is more convenient 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.

coords : Offset in the texture where to copy the source window.