class SFML::VertexArray

Batched geometry: a single CSFML draw call shipping many vertices to the GPU at once. This is how you draw thousands of particles, custom meshes, or tile maps without the per-shape overhead.

va = SFML::VertexArray.new(:triangles) va << SFML::Vertex.new([100, 100], color: SFML::Color.red) va << SFML::Vertex.new([200, 100], color: SFML::Color.green) va << SFML::Vertex.new([150, 200], color: SFML::Color.blue) window.draw(va)

Primitive types control how vertices form geometry: :points one isolated point per vertex :lines pairs of vertices form line segments :line_strip consecutive vertices form a chain of segments :triangles triples form independent triangles :triangle_strip each new vertex extends the strip :triangle_fan every vertex shares a fan-out with vertex 0

Constants

PRIMITIVE_INDEX: Primitive symbol → integer index Hash.
PRIMITIVE_TYPES: Order matches sfPrimitiveType in CSFML/Graphics/PrimitiveType.h.

Public Class Methods

new (primitive_type = :points, vertices = nil)

Source

# File lib/sfml/graphics/vertex_array.rb, line 30
def initialize(primitive_type = :points, vertices = nil)
  ptr = C::Graphics.sfVertexArray_create
  raise GraphicsError, "sfVertexArray_create returned NULL" if ptr.null?
  @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy))

  self.primitive_type = primitive_type
  vertices&.each { |v| append(v) }
end

Build an empty VertexArray. primitive_type chooses how vertices form geometry (see class doc). vertices is an optional initial list — same as calling append after.

Public Instance Methods

[] (index)

Source

# File lib/sfml/graphics/vertex_array.rb, line 86
def [](index)
  i = Integer(index)
  return nil if i < 0 || i >= size
  ptr = C::Graphics.sfVertexArray_getVertex(@handle, i)
  Vertex.from_native(C::Graphics::Vertex.new(ptr))
end

Read a vertex by index, or nil if out of range. Returns a fresh SFML::Vertex copy — mutate via va[i] = new_vertex to write back, not through the returned object.

[]= (index, vertex)

Source

# File lib/sfml/graphics/vertex_array.rb, line 95
def []=(index, vertex)
  i = Integer(index)
  # CSFML's sfVertexArray_getVertex aborts the process on out-of-range
  # access (it asserts), so we have to bounds-check on the Ruby side.
  raise IndexError, "vertex index #{i} out of range (size: #{size})" if i < 0 || i >= size

  ptr = C::Graphics.sfVertexArray_getVertex(@handle, i)
  cv = C::Graphics::Vertex.new(ptr)
  cv[:position][:x]   = vertex.position.x.to_f
  cv[:position][:y]   = vertex.position.y.to_f
  cv[:color][:r]      = vertex.color.r
  cv[:color][:g]      = vertex.color.g
  cv[:color][:b]      = vertex.color.b
  cv[:color][:a]      = vertex.color.a
  cv[:tex_coords][:x] = vertex.tex_coords.x.to_f
  cv[:tex_coords][:y] = vertex.tex_coords.y.to_f
  vertex
end

In-place vertex replacement. Bounds-checked on the Ruby side because CSFML’s getter aborts the process for out-of-range.

append (vertex)

Source

# File lib/sfml/graphics/vertex_array.rb, line 77
def append(vertex)
  C::Graphics.sfVertexArray_append(@handle, vertex.to_native)
  self
end

Add a vertex at the end. Returns self so calls can chain (va << v1 << v2).

bounds ()

Source

# File lib/sfml/graphics/vertex_array.rb, line 123
def bounds
  Rect.from_native(C::Graphics.sfVertexArray_getBounds(@handle))
end

Axis-aligned bounding box of all current vertices, as a Rect.

clear ()

Source

# File lib/sfml/graphics/vertex_array.rb, line 63
def clear
  C::Graphics.sfVertexArray_clear(@handle)
  self
end

Remove all vertices. Chainable.

dup ()

Source

# File lib/sfml/graphics/vertex_array.rb, line 134
def dup
  ptr = C::Graphics.sfVertexArray_copy(@handle)
  raise GraphicsError, "sfVertexArray_copy returned NULL" if ptr.null?
  copy = self.class.allocate
  copy.instance_variable_set(:@handle,
    FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy)))
  copy
end

Independent copy — vertices duplicated, future appends to one don’t affect the other.

each () { |self| ... }

Source

# File lib/sfml/graphics/vertex_array.rb, line 116
def each
  return enum_for(:each) unless block_given?
  size.times { |i| yield self[i] }
  self
end

Yield every vertex in order. Returns an Enumerator without a block — makes va.map, va.select, etc. work via Enumerable.

empty? (= size.zero?)

Source

# File lib/sfml/graphics/vertex_array.rb, line 60
  def empty? = size.zero?

  # Remove all vertices. Chainable.
  def clear
    C::Graphics.sfVertexArray_clear(@handle)
    self
  end

  # Resize to exactly `n` vertices, allocating defaults if growing.
  # Useful when you want to index-assign into the array directly.
  def resize(n)
    C::Graphics.sfVertexArray_resize(@handle, Integer(n))
    self
  end

  # Add a vertex at the end. Returns self so calls can chain
  # (`va << v1 << v2`).
  def append(vertex)
    C::Graphics.sfVertexArray_append(@handle, vertex.to_native)
    self
  end
  alias << append

  # Read a vertex by index, or nil if out of range. Returns a fresh
  # SFML::Vertex copy — mutate via `va[i] = new_vertex` to write back,
  # not through the returned object.
  def [](index)
    i = Integer(index)
    return nil if i < 0 || i >= size
    ptr = C::Graphics.sfVertexArray_getVertex(@handle, i)
    Vertex.from_native(C::Graphics::Vertex.new(ptr))
  end

  # In-place vertex replacement. Bounds-checked on the Ruby side
  # because CSFML's getter aborts the process for out-of-range.
  def []=(index, vertex)
    i = Integer(index)
    # CSFML's sfVertexArray_getVertex aborts the process on out-of-range
    # access (it asserts), so we have to bounds-check on the Ruby side.
    raise IndexError, "vertex index #{i} out of range (size: #{size})" if i < 0 || i >= size

    ptr = C::Graphics.sfVertexArray_getVertex(@handle, i)
    cv = C::Graphics::Vertex.new(ptr)
    cv[:position][:x]   = vertex.position.x.to_f
    cv[:position][:y]   = vertex.position.y.to_f
    cv[:color][:r]      = vertex.color.r
    cv[:color][:g]      = vertex.color.g
    cv[:color][:b]      = vertex.color.b
    cv[:color][:a]      = vertex.color.a
    cv[:tex_coords][:x] = vertex.tex_coords.x.to_f
    cv[:tex_coords][:y] = vertex.tex_coords.y.to_f
    vertex
  end

  # Yield every vertex in order. Returns an Enumerator without a
  # block — makes `va.map`, `va.select`, etc. work via Enumerable.
  def each
    return enum_for(:each) unless block_given?
    size.times { |i| yield self[i] }
    self
  end

  # Axis-aligned bounding box of all current vertices, as a Rect.
  def bounds
    Rect.from_native(C::Graphics.sfVertexArray_getBounds(@handle))
  end

  # Returns the draw on.
  def draw_on(target, states_ptr = nil) # :nodoc:
    target._draw_native(:VertexArray, @handle, states_ptr)
  end

  # Independent copy — vertices duplicated, future appends to one
  # don't affect the other.
  def dup
    ptr = C::Graphics.sfVertexArray_copy(@handle)
    raise GraphicsError, "sfVertexArray_copy returned NULL" if ptr.null?
    copy = self.class.allocate
    copy.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy)))
    copy
  end
  alias clone dup

  attr_reader :handle # :nodoc:
end

true if there are no vertices.

primitive_type ()

Source

# File lib/sfml/graphics/vertex_array.rb, line 40
def primitive_type
  PRIMITIVE_TYPES[C::Graphics.sfVertexArray_getPrimitiveType(@handle)] || :unknown
end

Current primitive type as a Symbol (one of PRIMITIVE_TYPES).

primitive_type= (type)

Source

# File lib/sfml/graphics/vertex_array.rb, line 46
def primitive_type=(type)
  code = PRIMITIVE_INDEX.fetch(type) do
    raise ArgumentError,
          "Unknown primitive type: #{type.inspect}. Expected one of: #{PRIMITIVE_TYPES.inspect}"
  end
  C::Graphics.sfVertexArray_setPrimitiveType(@handle, code)
end

Change the primitive type. Raises ArgumentError for unknown symbols.

resize (n)

Source

# File lib/sfml/graphics/vertex_array.rb, line 70
def resize(n)
  C::Graphics.sfVertexArray_resize(@handle, Integer(n))
  self
end

Resize to exactly n vertices, allocating defaults if growing. Useful when you want to index-assign into the array directly.

size (= C::Graphics.sfVertexArray_getVertexCount(@handle))

Source

# File lib/sfml/graphics/vertex_array.rb, line 55
    def size = C::Graphics.sfVertexArray_getVertexCount(@handle)
    alias length size
    alias count  size

    # `true` if there are no vertices.
    def empty? = size.zero?

    # Remove all vertices. Chainable.
    def clear
      C::Graphics.sfVertexArray_clear(@handle)
      self
    end

    # Resize to exactly `n` vertices, allocating defaults if growing.
    # Useful when you want to index-assign into the array directly.
    def resize(n)
      C::Graphics.sfVertexArray_resize(@handle, Integer(n))
      self
    end

    # Add a vertex at the end. Returns self so calls can chain
    # (`va << v1 << v2`).
    def append(vertex)
      C::Graphics.sfVertexArray_append(@handle, vertex.to_native)
      self
    end
    alias << append

    # Read a vertex by index, or nil if out of range. Returns a fresh
    # SFML::Vertex copy — mutate via `va[i] = new_vertex` to write back,
    # not through the returned object.
    def [](index)
      i = Integer(index)
      return nil if i < 0 || i >= size
      ptr = C::Graphics.sfVertexArray_getVertex(@handle, i)
      Vertex.from_native(C::Graphics::Vertex.new(ptr))
    end

    # In-place vertex replacement. Bounds-checked on the Ruby side
    # because CSFML's getter aborts the process for out-of-range.
    def []=(index, vertex)
      i = Integer(index)
      # CSFML's sfVertexArray_getVertex aborts the process on out-of-range
      # access (it asserts), so we have to bounds-check on the Ruby side.
      raise IndexError, "vertex index #{i} out of range (size: #{size})" if i < 0 || i >= size

      ptr = C::Graphics.sfVertexArray_getVertex(@handle, i)
      cv = C::Graphics::Vertex.new(ptr)
      cv[:position][:x]   = vertex.position.x.to_f
      cv[:position][:y]   = vertex.position.y.to_f
      cv[:color][:r]      = vertex.color.r
      cv[:color][:g]      = vertex.color.g
      cv[:color][:b]      = vertex.color.b
      cv[:color][:a]      = vertex.color.a
      cv[:tex_coords][:x] = vertex.tex_coords.x.to_f
      cv[:tex_coords][:y] = vertex.tex_coords.y.to_f
      vertex
    end

    # Yield every vertex in order. Returns an Enumerator without a
    # block — makes `va.map`, `va.select`, etc. work via Enumerable.
    def each
      return enum_for(:each) unless block_given?
      size.times { |i| yield self[i] }
      self
    end

    # Axis-aligned bounding box of all current vertices, as a Rect.
    def bounds
      Rect.from_native(C::Graphics.sfVertexArray_getBounds(@handle))
    end

    # Returns the draw on.
    def draw_on(target, states_ptr = nil) # :nodoc:
      target._draw_native(:VertexArray, @handle, states_ptr)
    end

    # Independent copy — vertices duplicated, future appends to one
    # don't affect the other.
    def dup
      ptr = C::Graphics.sfVertexArray_copy(@handle)
      raise GraphicsError, "sfVertexArray_copy returned NULL" if ptr.null?
      copy = self.class.allocate
      copy.instance_variable_set(:@handle,
        FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy)))
      copy
    end
    alias clone dup

    attr_reader :handle # :nodoc:
  end
end

Number of vertices currently in the array.