class SF::Image
inherits Reference
#
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
Constructors#
.from_file(*args, **kwargs) : self#
Shorthand for image = Image.new; image.load_from_file(...); image
Raises InitError on failure
.from_memory(*args, **kwargs) : self#
Shorthand for image = Image.new; image.load_from_memory(...); image
Raises InitError on failure
.from_stream(*args, **kwargs) : self#
Shorthand for image = Image.new; image.load_from_stream(...); image
Raises InitError on failure
Methods#
#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
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, alpha blending is applied from the source pixels to the destination pixels using the over operator. If it is false, the source pixels are copied unchanged with their alpha value.
See https://en.wikipedia.org/wiki/Alpha_compositing for details on the over operator.
- 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(width : Int, height : Int, color : Color = Color.new(0, 0, 0))#
Create the image and fill it with a unique color
- width - Width of the image
- height - Height of the image
- color - Fill color
#create(width : Int, height : Int, pixels : Pointer(UInt8))#
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_mask_from_color(color : Color, alpha : Int = 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.
- color - Color to make transparent
- alpha - Alpha value to assign to transparent pixels
#dup : Image#
Returns a shallow copy of this object.
This allocates a new object and copies the contents of
self into it.
#get_pixel(x : Int, y : Int) : Color#
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_from_file(filename : String) : Bool#
Load the image from a file on disk
The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm. 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_from_memory(data : Slice) : Bool#
Load the image from a file in memory
The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm. 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_from_stream(stream : InputStream) : Bool#
Load the image from a custom stream
The supported image formats are bmp, png, tga, jpg, gif, psd, hdr, pic and pnm. Some format options are not supported, like jpeg with arithmetic coding or ASCII pnm. 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
#pixels_ptr : ::Pointer(UInt8)#
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_to_file(filename : String) : Bool#
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
#save_to_memory(output : MemoryBuffer, format : String) : Bool#
Save the image to a buffer in memory
The format of the image must be specified. The supported image formats are bmp, png, tga and jpg. This function fails if the image is empty, or if the format was invalid.
- output - Buffer to fill with encoded data
- format - Encoding format to use
Returns: True if saving was successful
See also: create, load_from_file, load_from_memory, save_to_file
#set_pixel(x : Int, y : Int, color : Color)#
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
#size : Vector2u#
Return the size (width and height) of the image
Returns: Size of the image, in pixels