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 =

Comparison symbol → integer Hash.

COMPARISONS.each_with_index.to_h.freeze
OPERATIONS =

Order matches sfStencilUpdateOperation in CSFML 3.

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

Update-op symbol → integer Hash.

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) 


41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 41

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)

The comparison, update operation, reference, mask, only write mask components.



39
40
41
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 39

def comparison
  @comparison
end

#mask ⇒ Object (readonly)

The comparison, update operation, reference, mask, only write mask components.



39
40
41
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 39

def mask
  @mask
end

#only_write_mask ⇒ Object (readonly)

The comparison, update operation, reference, mask, only write mask components.



39
40
41
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 39

def only_write_mask
  @only_write_mask
end

#reference ⇒ Object (readonly)

The comparison, update operation, reference, mask, only write mask components.



39
40
41
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 39

def reference
  @reference
end

#update_operation ⇒ Object (readonly)

The comparison, update operation, reference, mask, only write mask components.



39
40
41
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 39

def update_operation
  @update_operation
end

Instance Method Details

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



56
57
58
59
60
61
62
63
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 56

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

Returns the hash.



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

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

#to_s ⇒ Object Also known as: inspect

Returns the to s.



69
70
71
72
 
# File 'lib/sfml/graphics/stencil_mode.rb', line 69

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