class SF::Image
- SF::Image
- Reference
- Object
Overview
Class for loading, manipulating and saving images
SF::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.
SF::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 a SF::Color
.
All the functions that return an array of pixels follow
this rule, and all parameters that you pass to SF::Image
functions (such as load_from_memory) must use this
representation as well.
A SF::Image
can be copied, but it is a heavy resource and
if possible you should always use [const] references to
pass or return them to avoid useless copies.
Usage example:
# Load an image file from a file
background = SF::Image.from_file("background.jpg")
# Create a 20x20 image filled with black color
image = SF::Image.new(20, 20, SF::Color::Black)
# Copy image1 on image2 at position (10, 10)
image.copy(background, 10, 10)
# Make the top-left pixel transparent
color = image.get_pixel(0, 0)
color.a = 128
image.set_pixel(0, 0, color)
# Save the image to a file
image.save_to_file("result.png") || error
See also: SF::Texture
Defined in:
graphics/obj.crConstructors
-
.from_file(*args, **kwargs) : self
Shorthand for
image = Image.new; image.load_from_file(...); image
-
.from_memory(*args, **kwargs) : self
Shorthand for
image = Image.new; image.load_from_memory(...); image
-
.from_stream(*args, **kwargs) : self
Shorthand for
image = Image.new; image.load_from_stream(...); image
-
.new
Default constructor
-
.new(*args, **kwargs) : self
Shorthand for
image = Image.new; image.create(...); image
Instance Method Summary
-
#copy(source : Image, dest_x : Int, dest_y : Int, source_rect : IntRect = IntRect.new(0, 0, 0, 0), apply_alpha : Bool = false)
Copy pixels from another image onto this one
-
#create(width : Int, height : Int, color : Color = Color.new(0, 0, 0))
Create the image and fill it with a unique color
-
#create(width : Int, height : Int, pixels : Pointer(UInt8))
Create the image from an array of pixels
-
#create_mask_from_color(color : Color, alpha : Int = 0)
Create a transparency mask from a specified color-key
-
#dup : Image
Returns a shallow copy of this object.
-
#finalize
Destructor
-
#flip_horizontally
Flip the image horizontally (left <-> right)
-
#flip_vertically
Flip the image vertically (top <-> bottom)
-
#get_pixel(x : Int, y : Int) : Color
Get the color of a pixel
-
#load_from_file(filename : String) : Bool
Load the image from a file on disk
-
#load_from_memory(data : Slice) : Bool
Load the image from a file in memory
-
#load_from_stream(stream : InputStream) : Bool
Load the image from a custom stream
-
#pixels_ptr : Pointer(UInt8)
Get a read-only pointer to the array of pixels
-
#save_to_file(filename : String) : Bool
Save the image to a file on disk
-
#set_pixel(x : Int, y : Int, color : Color)
Change the color of a pixel
-
#size : Vector2u
Return the size (width and height) of the image
Constructor Detail
Instance Method Detail
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 SF::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.
- source - Source image to copy
- dest_x - X coordinate of the destination position
- dest_y - Y coordinate of the destination position
- source_rect - Sub-rectangle of the source image to copy
- apply_alpha - Should the copy take into account the source transparency?
Create the image and fill it with a unique color
- width - Width of the image
- height - Height of the image
- color - Fill color
Create the image from an array of pixels
The pixel array is assumed to contain 32-bits RGBA pixels, and have the given width and height. If not, this is an undefined behavior. If pixels is null, an empty image is created.
- width - Width of the image
- height - Height of the image
- pixels - Array of pixels to copy to the image
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.
- color - Color to make transparent
- alpha - Alpha value to assign to transparent pixels
Returns a shallow copy of this object.
This allocates a new object and copies the contents of
self
into it.
Get the color of a pixel
This function doesn't check the validity of the pixel coordinates, using out-of-range values will result in an undefined behavior.
- x - X coordinate of pixel to get
- y - Y coordinate of pixel to get
Returns: Color of the pixel at coordinates (x, y)
See also: pixel=
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, the image is left unchanged.
- filename - Path of the image file to load
Returns: True if loading was successful
See also: #load_from_memory
, #load_from_stream
, #save_to_file
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, the image is left unchanged.
- data - Slice containing the file data in memory
Returns: True if loading was successful
See also: #load_from_file
, #load_from_stream
Load the image from a custom stream
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, the image is left unchanged.
- stream - Source stream to read from
Returns: True if loading was successful
See also: #load_from_file
, #load_from_memory
Get a read-only pointer to the array of pixels
The returned value points to an array of RGBA pixels made of
8 bits integers components. The size of the array is
width * height * 4 (size().x * #size()
.y * 4).
WARNING The returned pointer may become invalid if you modify the image, so you should never store it for too long. If the image is empty, a null pointer is returned.
Returns: Read-only pointer to the array of pixels
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. This function fails if the image is empty.
- filename - Path of the file to save
Returns: True if saving was successful
See also: #create
, #load_from_file
, #load_from_memory
Change the color of a pixel
This function doesn't check the validity of the pixel coordinates, using out-of-range values will result in an undefined behavior.
- x - X coordinate of pixel to change
- y - Y coordinate of pixel to change
- color - New color of the pixel
See also: pixel
Return the size (width and height) of the image
Returns: Size of the image, in pixels