Class: SFML::StencilMode

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

Overview

How a draw call interacts with the stencil buffer. The classic use is masking — first you draw a “mask” shape that writes a value into the stencil buffer, then you draw the masked content with a comparison that only lets pixels through where the stencil matches.

target.clear(SFML::Color.black, stencil: 0)

# Phase 1 — write the mask shape into the stencil buffer.
write = SFML::StencilMode.new(
  comparison: :always, update_operation: :replace, reference: 1,
  only_write_mask: true,   # don't actually paint colour
)
target.draw(mask_circle, stencil_mode: write)

# Phase 2 — draw the content; only pixels where stencil == 1
# survive.
read = SFML::StencilMode.new(
  comparison: :equal, update_operation: :keep, reference: 1,
)
target.draw(scene, stencil_mode: read)

‘stencilOnly` (`only_write_mask:`) is a niche flag — set it to true on the mask-write pass if you don’t want the mask shape itself to be visible in the colour buffer.

Constant Summary collapse

COMPARISONS =

Order matches sfStencilComparison in CSFML 3.

%i[never less less_equal greater greater_equal equal not_equal always].freeze
COMPARISON_INDEX = 
COMPARISONS.each_with_index.to_h.freeze
OPERATIONS =

Order matches sfStencilUpdateOperation in CSFML 3.

%i[keep zero replace increment decrement invert].freeze
OPERATION_INDEX = 
OPERATIONS.each_with_index.to_h.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(comparison: :always, update_operation: :keep, reference: 0, mask: 0xFFFFFFFF, only_write_mask: false) ⇒ StencilMode

Returns a new instance of StencilMode.

Raises:

  • (ArgumentError) 


38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 38

def initialize(comparison: :always, update_operation: :keep,
               reference: 0, mask: 0xFFFFFFFF, only_write_mask: false)
  raise ArgumentError, "Unknown stencil comparison: #{comparison.inspect}" \
    unless COMPARISON_INDEX.key?(comparison)
  raise ArgumentError, "Unknown stencil update_operation: #{update_operation.inspect}" \
    unless OPERATION_INDEX.key?(update_operation)

  @comparison       = comparison
  @update_operation = update_operation
  @reference        = Integer(reference)
  @mask             = Integer(mask)
  @only_write_mask  = !!only_write_mask
  freeze
end

Instance Attribute Details

#comparison ⇒ Object (readonly)

Returns the value of attribute comparison.



36
37
38
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 36

def comparison
  @comparison
end

#mask ⇒ Object (readonly)

Returns the value of attribute mask.



36
37
38
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 36

def mask
  @mask
end

#only_write_mask ⇒ Object (readonly)

Returns the value of attribute only_write_mask.



36
37
38
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 36

def only_write_mask
  @only_write_mask
end

#reference ⇒ Object (readonly)

Returns the value of attribute reference.



36
37
38
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 36

def reference
  @reference
end

#update_operation ⇒ Object (readonly)

Returns the value of attribute update_operation.



36
37
38
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 36

def update_operation
  @update_operation
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



53
54
55
56
57
58
59
60
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 53

def ==(other)
  other.is_a?(StencilMode) &&
    comparison == other.comparison &&
    update_operation == other.update_operation &&
    reference == other.reference &&
    mask == other.mask &&
    only_write_mask == other.only_write_mask
end

#hash ⇒ Object 



62
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 62

def hash = [comparison, update_operation, reference, mask, only_write_mask].hash

#to_s ⇒ Object Also known as: inspect 



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

def to_s
  "StencilMode(#{comparison}, #{update_operation}, ref=#{reference}, " \
    "mask=#{format('0x%08X', mask)}, only_write=#{only_write_mask})"
end