Class: SFML::Texture

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

Overview

A 2D image stored on the GPU. Used by Sprite (and shapes) to draw textured geometry. Build one with .load:

tex = SFML::Texture.load("assets/hero.png")
tex = SFML::Texture.load("assets/tile.png", smooth: true, repeated: true)

Constant Summary collapse

COORDINATE_TYPES =

Bind this texture to the active OpenGL texture unit. coord is one of :normalized (default — UVs in [0..1]) or :pixels (UVs in [0..size]). Useful when mixing raw OpenGL with SFML rendering. Pass nil to unbind:

`SFML::Texture.unbind`.
{normalized: 0, pixels: 1}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#handle ⇒ Object (readonly)

:nodoc:



236
237
238
 
# File 'lib/sfml/graphics/texture.rb', line 236

def handle
  @handle
end

Class Method Details

._borrow(ptr) ⇒ Object

Internal — borrow a CSFML-owned sfTexture* (e.g. one returned by sfFont_getTexture) without registering an auto-destroy hook. The owning object is responsible for outliving any draw call that uses this borrowed handle.



242
243
244
245
246
 
# File 'lib/sfml/graphics/texture.rb', line 242

def self._borrow(ptr)
  tex = allocate
  tex.instance_variable_set(:@handle, ptr)
  tex
end

.create(width, height, srgb: false) ⇒ Object

Allocate a blank texture on the GPU at the given size — use update(image) afterwards to upload pixels. Useful when you'll be filling the texture from a procedurally-generated Image or repeatedly streaming pixel data into it.

Raises:



32
33
34
35
36
37
38
39
40
41
 
# File 'lib/sfml/graphics/texture.rb', line 32

def self.create(width, height, srgb: false)
  size = C::System::Vector2u.new
  size[:x] = Integer(width); size[:y] = Integer(height)
  ptr = srgb ? C::Graphics.sfTexture_createSrgb(size) : C::Graphics.sfTexture_create(size)
  raise GraphicsError, "sfTexture_create returned NULL — out of GPU memory?" if ptr.null?

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

.from_image(image, smooth: false, repeated: false, srgb: false) ⇒ Object

Upload a CPU-side SFML::Image to the GPU as a new Texture. Keeps the RGBA byte order and dimensions of the source image.

Raises:

  • (ArgumentError) 


83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/sfml/graphics/texture.rb', line 83

def self.from_image(image, smooth: false, repeated: false, srgb: false)
  raise ArgumentError, "Texture.from_image needs a SFML::Image" unless image.is_a?(Image)

  ptr = srgb \
    ? C::Graphics.sfTexture_createSrgbFromImage(image.handle, nil) \
    : C::Graphics.sfTexture_createFromImage(image.handle, nil)
  raise LoadError, "sfTexture_createFromImage returned NULL" if ptr.null?

  tex = allocate
  tex.send(:_take_ownership, ptr)
  tex.smooth   = smooth
  tex.repeated = repeated
  tex
end

.from_memory(bytes, smooth: false, repeated: false, srgb: false) ⇒ Object

Decode + upload a Ruby String of bytes (PNG, JPG, BMP, …) as a texture. Useful for embedded assets / network responses that bypass the disk.

Raises:

  • (ArgumentError) 


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

def self.from_memory(bytes, smooth: false, repeated: false, srgb: false)
  raise ArgumentError, "expected a String, got #{bytes.class}" unless bytes.is_a?(String)

  buf = FFI::MemoryPointer.new(:uint8, bytes.bytesize)
  buf.write_bytes(bytes)
  ptr = srgb \
    ? C::Graphics.sfTexture_createSrgbFromMemory(buf, bytes.bytesize, nil) \
    : C::Graphics.sfTexture_createFromMemory(buf, bytes.bytesize, nil)
  raise LoadError, "sfTexture_createFromMemory returned NULL — unsupported format?" if ptr.null?

  tex = allocate
  tex.send(:_take_ownership, ptr)
  tex.smooth   = smooth
  tex.repeated = repeated
  tex
end

.from_stream(io, smooth: false, repeated: false, srgb: false) ⇒ Object

Load a texture from any Ruby IO-like object (File, StringIO, or anything answering read/seek/pos/size). Useful for assets inside a zip archive, served over a socket, or generated on the fly.

Raises:



67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/sfml/graphics/texture.rb', line 67

def self.from_stream(io, smooth: false, repeated: false, srgb: false)
  stream = SFML::InputStream.new(io)
  ptr = srgb \
    ? C::Graphics.sfTexture_createSrgbFromStream(stream.to_ptr, nil) \
    : C::Graphics.sfTexture_createFromStream(stream.to_ptr, nil)
  raise LoadError, "sfTexture_createFromStream returned NULL — unsupported format?" if ptr.null?

  tex = allocate
  tex.send(:_take_ownership, ptr)
  tex.smooth   = smooth
  tex.repeated = repeated
  tex
end

.load(path, smooth: false, repeated: false, srgb: false) ⇒ Object

Load a texture from a file on disk.

Pass srgb: true if the source pixels are in sRGB-encoded gamma space (most photo/PNG art assets) and you want the GPU to gamma-decode on sample so blending happens in linear space. Pair with RenderWindow#new(..., srgb_capable: true) and your final framebuffer will gamma-encode on present.

Raises:



15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/sfml/graphics/texture.rb', line 15

def self.load(path, smooth: false, repeated: false, srgb: false)
  ptr = srgb \
    ? C::Graphics.sfTexture_createSrgbFromFile(path.to_s, nil) \
    : C::Graphics.sfTexture_createFromFile(path.to_s, nil)
  raise LoadError, "Could not load texture from #{path.inspect}" if ptr.null?

  tex = allocate
  tex.send(:_take_ownership, ptr)
  tex.smooth   = smooth
  tex.repeated = repeated
  tex
end

.maximum_size ⇒ Object

Maximum texture dimension the driver will allocate. Tied to the GL state, so it's a class-level call (no instance).



168
169
170
 
# File 'lib/sfml/graphics/texture.rb', line 168

def self.maximum_size
  C::Graphics.sfTexture_getMaximumSize
end

.unbind ⇒ Object

Returns the self.



162
163
164
 
# File 'lib/sfml/graphics/texture.rb', line 162

def self.unbind
  C::Graphics.sfTexture_bind(nil, 0)
end

Instance Method Details

#bind(coord: :normalized) ⇒ Object

Returns the bind.

Raises:

  • (ArgumentError) 


156
157
158
159
 
# File 'lib/sfml/graphics/texture.rb', line 156

def bind(coord: :normalized)
  raise ArgumentError, "coord must be :normalized or :pixels" unless COORDINATE_TYPES.key?(coord)
  C::Graphics.sfTexture_bind(@handle, COORDINATE_TYPES[coord])
end

#dup ⇒ Object Also known as: clone

Deep copy. The returned texture has its own GPU memory.

Raises:



173
174
175
176
177
178
179
180
 
# File 'lib/sfml/graphics/texture.rb', line 173

def dup
  ptr = C::Graphics.sfTexture_copy(@handle)
  raise GraphicsError, "sfTexture_copy returned NULL" if ptr.null?

  tex = self.class.allocate
  tex.send(:_take_ownership, ptr)
  tex
end

#generate_mipmap ⇒ Object

Generate mipmaps for this texture. Returns true if the GPU honoured it. Required for the _MIPMAP_* minification filters; otherwise downscaled samples alias.



146
 
# File 'lib/sfml/graphics/texture.rb', line 146

def generate_mipmap = C::Graphics.sfTexture_generateMipmap(@handle)

#native_handle ⇒ Object

The OpenGL texture-object name (a glGenTextures ID). Useful when feeding this texture into raw GL calls.



208
 
# File 'lib/sfml/graphics/texture.rb', line 208

def native_handle = C::Graphics.sfTexture_getNativeHandle(@handle)

#repeated=(value) ⇒ Object

Set the repeated.



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

def repeated=(value)
  C::Graphics.sfTexture_setRepeated(@handle, !!value)
end

#repeated? ⇒ Boolean

true if repeated.

Returns:

  • (Boolean) 


133
 
# File 'lib/sfml/graphics/texture.rb', line 133

def repeated? = C::Graphics.sfTexture_isRepeated(@handle)

#resize(width, height, srgb: false) ⇒ Object

Reallocate this texture's GPU memory at a new size. Returns false if the GPU rejects the size (driver limit / OOM); the texture's contents become undefined on success. Pass srgb: true to re-allocate as an sRGB-encoded texture.



187
188
189
190
191
192
193
194
195
 
# File 'lib/sfml/graphics/texture.rb', line 187

def resize(width, height, srgb: false)
  size = C::System::Vector2u.new
  size[:x] = Integer(width); size[:y] = Integer(height)
  if srgb
    C::Graphics.sfTexture_resizeSrgb(@handle, size)
  else
    C::Graphics.sfTexture_resize(@handle, size)
  end
end

#size ⇒ Object

Returns the size.



120
121
122
 
# File 'lib/sfml/graphics/texture.rb', line 120

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

#smooth=(value) ⇒ Object

Set the smooth.



128
129
130
 
# File 'lib/sfml/graphics/texture.rb', line 128

def smooth=(value)
  C::Graphics.sfTexture_setSmooth(@handle, !!value)
end

#smooth? ⇒ Boolean

true if smooth.

Returns:

  • (Boolean) 


125
 
# File 'lib/sfml/graphics/texture.rb', line 125

def smooth?  = C::Graphics.sfTexture_isSmooth(@handle)

#srgb? ⇒ Boolean

true if srgb.

Returns:

  • (Boolean) 


141
 
# File 'lib/sfml/graphics/texture.rb', line 141

def srgb? = C::Graphics.sfTexture_isSrgb(@handle)

#swap(other) ⇒ Object

Atomically swap the GPU memory between two textures — cheaper than dup + reassign for double-buffer-style patterns (paint-buffer ⇄ visible-buffer).

Raises:

  • (ArgumentError) 


200
201
202
203
204
 
# File 'lib/sfml/graphics/texture.rb', line 200

def swap(other)
  raise ArgumentError, "Texture#swap needs a Texture" unless other.is_a?(Texture)
  C::Graphics.sfTexture_swap(@handle, other.handle)
  self
end

#to_image ⇒ Object

Read the texture back from the GPU into a fresh SFML::Image. Slow — useful for screenshots or post-processing inspection.

Raises:



111
112
113
114
115
116
117
 
# File 'lib/sfml/graphics/texture.rb', line 111

def to_image
  ptr = C::Graphics.sfTexture_copyToImage(@handle)
  raise GraphicsError, "sfTexture_copyToImage returned NULL" if ptr.null?
  img = Image.allocate
  img.send(:_take_ownership, ptr)
  img
end

#update(image) ⇒ Object

Re-upload an Image's pixels to this texture in place. The image must match the texture's size — use this for animated procedural textures (paint-buffer style) without re-allocating GPU memory.

Raises:

  • (ArgumentError) 


101
102
103
104
105
106
107
 
# File 'lib/sfml/graphics/texture.rb', line 101

def update(image)
  raise ArgumentError, "Texture#update needs a SFML::Image" unless image.is_a?(Image)
  offset = C::System::Vector2u.new
  offset[:x] = 0; offset[:y] = 0
  C::Graphics.sfTexture_updateFromImage(@handle, image.handle, offset)
  self
end

#update_from_render_window(window, offset: [0, 0]) ⇒ Object

Read the back-buffer of a RenderWindow into this texture at offset. Useful for capturing the rendered scene without re-drawing into a separate RenderTexture.

Raises:

  • (ArgumentError) 


222
223
224
225
226
 
# File 'lib/sfml/graphics/texture.rb', line 222

def update_from_render_window(window, offset: [0, 0])
  raise ArgumentError, "expected a RenderWindow" unless window.is_a?(RenderWindow)
  C::Graphics.sfTexture_updateFromRenderWindow(@handle, window.handle, _vec2u(offset))
  self
end

#update_from_texture(source, offset: [0, 0]) ⇒ Object

Upload the contents of another texture into this one at offset ([x, y]). Both textures must remain alive for the duration of the call.

Raises:

  • (ArgumentError) 


213
214
215
216
217
 
# File 'lib/sfml/graphics/texture.rb', line 213

def update_from_texture(source, offset: [0, 0])
  raise ArgumentError, "expected a Texture" unless source.is_a?(Texture)
  C::Graphics.sfTexture_updateFromTexture(@handle, source.handle, _vec2u(offset))
  self
end

#update_from_window(window, offset: [0, 0]) ⇒ Object

Same as update_from_render_window for the bare Window (when you're managing GL yourself).

Raises:

  • (ArgumentError) 


230
231
232
233
234
 
# File 'lib/sfml/graphics/texture.rb', line 230

def update_from_window(window, offset: [0, 0])
  raise ArgumentError, "expected a Window" unless window.is_a?(SFML::Window)
  C::Graphics.sfTexture_updateFromWindow(@handle, window.handle, _vec2u(offset))
  self
end