class SF::Image

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

Constructors

Instance Method Summary

Constructor Detail

def self.from_file(*args, **kwargs) : self #

Shorthand for image = Image.new; image.load_from_file(...); image

Raises InitError on failure


[View source]
def self.from_memory(*args, **kwargs) : self #

Shorthand for image = Image.new; image.load_from_memory(...); image

Raises InitError on failure


[View source]
def self.from_stream(*args, **kwargs) : self #

Shorthand for image = Image.new; image.load_from_stream(...); image

Raises InitError on failure


[View source]
def self.new #

Default constructor

Creates an empty image.


[View source]
def self.new(*args, **kwargs) : self #

Shorthand for image = Image.new; image.create(...); image


[View source]

Instance Method Detail

def 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, 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?

[View source]
def 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

[View source]
def 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

[View source]
def 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

[View source]
def dup : Image #
Description copied from class Reference

Returns a shallow copy of this object.

This allocates a new object and copies the contents of self into it.


[View source]
def finalize #

Destructor


[View source]
def flip_horizontally #

Flip the image horizontally (left <-> right)


[View source]
def flip_vertically #

Flip the image vertically (top <-> bottom)


[View source]
def 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=


[View source]
def 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 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


[View source]
def 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 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


[View source]
def 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 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


[View source]
def 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


[View source]
def 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


[View source]
def 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


[View source]
def size : Vector2u #

Return the size (width and height) of the image

Returns: Size of the image, in pixels


[View source]