Class: SFML::Image

Inherits:
Object
  • Object
show all
Defined in:
lib/sfml/graphics/image.rb

Overview

CPU-side bitmap. Lives in main memory and supports per-pixel reads / writes — handy for procedural generation, screenshots, masks, and anything that needs to inspect or modify pixel data before upload.

img = SFML::Image.new(800, 600, fill: SFML::Color.cornflower_blue)
img = SFML::Image.load("assets/hero.png")

img[10, 20] = SFML::Color.red
img[10, 20]                       #=> Color(255, 0, 0, 255)

img.flip_vertically
img.save("out.png")

Convert to a GPU-side texture for drawing:

tex = SFML::Texture.from_image(img)
sprite = SFML::Sprite.new(tex)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(width, height, fill: nil) ⇒ Image

Create a blank image of the given size. With ‘fill:` it’s filled with that colour; without, with transparent black.

Raises:



22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/sfml/graphics/image.rb', line 22

def initialize(width, height, fill: nil)
  size = C::System::Vector2u.new
  size[:x] = Integer(width)
  size[:y] = Integer(height)

  ptr = if fill
          C::Graphics.sfImage_createFromColor(size, fill.to_native)
        else
          C::Graphics.sfImage_create(size)
        end
  raise Error, "sfImage_create returned NULL" if ptr.null?
  _take_ownership(ptr)
end

Instance Attribute Details

#handle ⇒ Object (readonly)

:nodoc:



140
141
142
 
# File 'lib/sfml/graphics/image.rb', line 140

def handle
  @handle
end

Class Method Details

.from_pixels(width, height, pixels) ⇒ Object

Build an image from a raw RGBA byte string. ‘pixels` must be exactly width*height*4 bytes, row-major from the top-left.

Raises:

  • (ArgumentError) 


46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/sfml/graphics/image.rb', line 46

def self.from_pixels(width, height, pixels)
  expected = Integer(width) * Integer(height) * 4
  raise ArgumentError, "expected #{expected} bytes, got #{pixels.bytesize}" if pixels.bytesize != expected

  buf = FFI::MemoryPointer.new(:uint8, expected)
  buf.write_bytes(pixels)

  size = C::System::Vector2u.new
  size[:x] = Integer(width)
  size[:y] = Integer(height)
  ptr = C::Graphics.sfImage_createFromPixels(size, buf)
  raise Error, "sfImage_createFromPixels returned NULL" if ptr.null?

  img = allocate
  img.send(:_take_ownership, ptr)
  img
end

.load(path) ⇒ Object

Raises:



36
37
38
39
40
41
42
 
# File 'lib/sfml/graphics/image.rb', line 36

def self.load(path)
  ptr = C::Graphics.sfImage_createFromFile(path.to_s)
  raise Error, "Could not load image from #{path.inspect}" if ptr.null?
  img = allocate
  img.send(:_take_ownership, ptr)
  img
end

Instance Method Details

#[](x, y) ⇒ Object

Read the colour of a single pixel.



72
73
74
75
76
 
# File 'lib/sfml/graphics/image.rb', line 72

def [](x, y)
  coord = C::System::Vector2u.new
  coord[:x] = Integer(x); coord[:y] = Integer(y)
  Color.from_native(C::Graphics.sfImage_getPixel(@handle, coord))
end

#[]=(x, y, color) ⇒ Object

Write a single pixel.



79
80
81
82
83
 
# File 'lib/sfml/graphics/image.rb', line 79

def []=(x, y, color)
  coord = C::System::Vector2u.new
  coord[:x] = Integer(x); coord[:y] = Integer(y)
  C::Graphics.sfImage_setPixel(@handle, coord, color.to_native)
end

#flip_horizontally ⇒ Object 



130
131
132
133
 
# File 'lib/sfml/graphics/image.rb', line 130

def flip_horizontally
  C::Graphics.sfImage_flipHorizontally(@handle)
  self
end

#flip_vertically ⇒ Object 



135
136
137
138
 
# File 'lib/sfml/graphics/image.rb', line 135

def flip_vertically
  C::Graphics.sfImage_flipVertically(@handle)
  self
end

#height ⇒ Object 



69
 
# File 'lib/sfml/graphics/image.rb', line 69

def height = size.y

#mask_color!(color, alpha: 0) ⇒ Object

Replace any pixel matching ‘color` with that colour at `alpha` opacity — typical use is to turn a fixed background colour transparent: img.mask_color!(SFML::Color.magenta, alpha: 0).



125
126
127
128
 
# File 'lib/sfml/graphics/image.rb', line 125

def mask_color!(color, alpha: 0)
  C::Graphics.sfImage_createMaskFromColor(@handle, color.to_native, Integer(alpha))
  self
end

#pixels ⇒ Object

Write the entire pixel buffer back as a Ruby String. Useful for piping to image-processing libraries or writing custom file formats. Format: width*height*4 bytes, RGBA, row-major from top-left.



88
89
90
91
 
# File 'lib/sfml/graphics/image.rb', line 88

def pixels
  ptr = C::Graphics.sfImage_getPixelsPtr(@handle)
  ptr.read_bytes(width * height * 4)
end

#save(path) ⇒ Object

Raises:



93
94
95
96
97
 
# File 'lib/sfml/graphics/image.rb', line 93

def save(path)
  ok = C::Graphics.sfImage_saveToFile(@handle, path.to_s)
  raise Error, "Could not save image to #{path.inspect}" unless ok
  path
end

#save_to_memory(format) ⇒ Object

Encode the image as ‘format` (“png”, “jpg”, “bmp”, or “tga”) and return the encoded bytes as a Ruby String. Useful for sending screenshots over the network, generating data: URLs, piping into an image-processing library, etc., without touching the disk.

png_bytes = img.save_to_memory("png")
File.binwrite("out.png", png_bytes)

Raises:



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/sfml/graphics/image.rb', line 106

def save_to_memory(format)
  buffer = C::System.sfBuffer_create
  raise Error, "sfBuffer_create returned NULL" if buffer.null?

  begin
    ok = C::Graphics.sfImage_saveToMemory(@handle, buffer, format.to_s)
    raise Error, "Could not encode image as #{format.inspect}" unless ok

    size = C::System.sfBuffer_getSize(buffer)
    data = C::System.sfBuffer_getData(buffer)
    data.read_bytes(size)
  ensure
    C::System.sfBuffer_destroy(buffer)
  end
end

#size ⇒ Object 



64
65
66
 
# File 'lib/sfml/graphics/image.rb', line 64

def size
  Vector2.from_native(C::Graphics.sfImage_getSize(@handle))
end

#width ⇒ Object 



68
 
# File 'lib/sfml/graphics/image.rb', line 68

def width  = size.x