Teek API Documentation

Teek::SDL2 Module

GPU-accelerated 2D rendering via SDL2, embedded inside Tk windows.

Teek::SDL2 lets you drop an SDL2 hardware-accelerated surface into any Tk application. The surface lives inside a Tk frame so it coexists with normal Tk widgets (buttons, labels, menus) while all pixel work is GPU-driven.

The main entry point is Viewport, which creates a Tk frame, obtains its native window handle, and hands it to SDL2 for rendering.

Class Methods ↑

_viewports

@api private

View source ▼ 
def _viewports
  @_viewports
end
GitHub

available?

Whether at least one audio output device is available.

Returns Boolean

device_count

Number of audio output devices detected by SDL2.

Returns Integer

driver_name

Name of the current SDL2 audio driver (e.g. “wasapi”, “dummy”).

Returns String, nil

Audio (C-defined module functions)

channel_paused?(channel)

Whether the given channel is paused.

Parameters
  • channel Integer

Returns Boolean

View source ▼ 
static VALUE
mixer_channel_paused_p(VALUE mod, VALUE channel)
{
    return Mix_Paused(NUM2INT(channel)) ? Qtrue : Qfalse;
}
GitHub

channel_volume(channel, vol -1)

Set or query volume for a channel.

Parameters
  • channel Integer
  • vol Integer — 0–128, or -1 to query without changing

Returns Integer — current volume

View source ▼ 
static VALUE
mixer_channel_volume(int argc, VALUE *argv, VALUE mod)
{
    VALUE ch, vol;
    rb_scan_args(argc, argv, "11", &ch, &vol);
    int v = NIL_P(vol) ? -1 : NUM2INT(vol);
    return INT2NUM(Mix_Volume(NUM2INT(ch), v));
}
GitHub

close_audio

Shut down the audio mixer and free resources.

Returns nil

View source ▼ 
static VALUE
mixer_close_audio(VALUE mod)
{
    if (mixer_initialized) {
        Mix_CloseAudio();
        mixer_initialized = 0;
    }
    return Qnil;
}
GitHub

fade_out_channel(channel, ms)

Gradually fade out a channel.

Parameters
  • channel Integer
  • ms Integer — fade duration in milliseconds

Returns nil

View source ▼ 
static VALUE
mixer_fade_out_channel(VALUE mod, VALUE channel, VALUE ms)
{
    Mix_FadeOutChannel(NUM2INT(channel), NUM2INT(ms));
    return Qnil;
}
GitHub

fade_out_music(ms)

Gradually fade out the currently playing music.

Parameters
  • ms Integer — fade duration in milliseconds

Returns nil

View source ▼ 
static VALUE
mixer_fade_out_music(VALUE mod, VALUE ms)
{
    Mix_FadeOutMusic(NUM2INT(ms));
    return Qnil;
}
GitHub

halt(channel)

Immediately stop playback on a channel.

Parameters
  • channel Integer — channel number (returned by Sound#play)

Returns nil

View source ▼ 
static VALUE
mixer_halt_channel(VALUE mod, VALUE channel)
{
    Mix_HaltChannel(NUM2INT(channel));
    return Qnil;
}
GitHub

master_volume

Current master volume (requires SDL2_mixer >= 2.6).

Returns Integer — 0–128

@raise NotImplementedError if SDL2_mixer < 2.6

View source ▼ 
static VALUE
mixer_get_master_volume(VALUE mod)
{
#ifdef HAVE_MIX_MASTER_VOLUME
    return INT2NUM(Mix_MasterVolume(-1));
#else
    rb_raise(rb_eNotImpError,
             "master_volume requires SDL2_mixer >= 2.6 (you have %d.%d.%d)",
             SDL_MIXER_MAJOR_VERSION, SDL_MIXER_MINOR_VERSION,
             SDL_MIXER_PATCHLEVEL);
    return Qnil;
#endif
}
GitHub

master_volume=(vol)

Set the master volume (requires SDL2_mixer >= 2.6).

Parameters
  • vol Integer — 0–128

Returns Integer — previous volume

@raise NotImplementedError if SDL2_mixer < 2.6

View source ▼ 
static VALUE
mixer_set_master_volume(VALUE mod, VALUE vol)
{
#ifdef HAVE_MIX_MASTER_VOLUME
    int v = NUM2INT(vol);
    if (v < 0) v = 0;
    if (v > MIX_MAX_VOLUME) v = MIX_MAX_VOLUME;
    return INT2NUM(Mix_MasterVolume(v));
#else
    rb_raise(rb_eNotImpError,
             "master_volume requires SDL2_mixer >= 2.6 (you have %d.%d.%d)",
             SDL_MIXER_MAJOR_VERSION, SDL_MIXER_MINOR_VERSION,
             SDL_MIXER_PATCHLEVEL);
    return Qnil; /* unreachable */
#endif
}
GitHub

open_audio

Explicitly initialize the audio mixer. Safe to call multiple times. Called automatically by Sound and Music constructors.

Returns nil

View source ▼ 
static VALUE
mixer_open_audio(VALUE mod)
{
    ensure_mixer_init();
    return Qnil;
}
GitHub

pause_channel(channel)

Pause playback on a channel.

Parameters
  • channel Integer

Returns nil

View source ▼ 
static VALUE
mixer_pause_channel(VALUE mod, VALUE channel)
{
    Mix_Pause(NUM2INT(channel));
    return Qnil;
}
GitHub

playing?(channel)

Whether the given channel is currently playing.

Parameters
  • channel Integer

Returns Boolean

View source ▼ 
static VALUE
mixer_channel_playing_p(VALUE mod, VALUE channel)
{
    return Mix_Playing(NUM2INT(channel)) ? Qtrue : Qfalse;
}
GitHub

resume_channel(channel)

Resume a paused channel.

Parameters
  • channel Integer

Returns nil

View source ▼ 
static VALUE
mixer_resume_channel(VALUE mod, VALUE channel)
{
    Mix_Resume(NUM2INT(channel));
    return Qnil;
}
GitHub

start_audio_capture(path)

Begin recording mixed audio output to a WAV file. Everything that plays through the mixer (sounds, music) is captured.

Parameters
  • path String — output WAV file path

Returns nil

@raise RuntimeError if capture is already in progress

See also
View source ▼ 
static VALUE
mixer_start_capture(VALUE mod, VALUE path)
{
    if (capture_file) {
        rb_raise(rb_eRuntimeError, "audio capture already in progress");
    }

    ensure_mixer_init();

    int freq, channels;
    Uint16 format;
    if (!Mix_QuerySpec(&freq, &format, &channels)) {
        rb_raise(rb_eRuntimeError, "Mix_QuerySpec failed — mixer not open");
    }

    /* WAV files store little-endian PCM. We require the mixer opened
     * with a LE S16 format (the default on all modern platforms). */
    if (format != AUDIO_S16LSB) {
        rb_raise(rb_eRuntimeError,
                 "audio capture requires S16LE format (mixer opened with 0x%04x)",
                 (unsigned)format);
    }

    StringValue(path);
    capture_file = fopen(StringValueCStr(path), "wb");
    if (!capture_file) {
        rb_raise(rb_eRuntimeError, "cannot open capture file: %s",
                 StringValueCStr(path));
    }

    capture_freq       = freq;
    capture_channels   = channels;
    capture_data_bytes = 0;

    write_wav_header(capture_file, freq, channels, 0); /* placeholder */
    Mix_SetPostMix(capture_postmix, NULL);

    return Qnil;
}
GitHub

stop_audio_capture

Stop recording and finalize the WAV file. Safe to call even if no capture is in progress.

Returns nil

See also
View source ▼ 
static VALUE
mixer_stop_capture(VALUE mod)
{
    if (!capture_file) return Qnil;

    Mix_SetPostMix(NULL, NULL);

    /* Rewrite header with actual data size */
    fseek(capture_file, 0, SEEK_SET);
    write_wav_header(capture_file, capture_freq, capture_channels,
                     capture_data_bytes);
    fclose(capture_file);
    capture_file       = NULL;
    capture_data_bytes = 0;

    return Qnil;
}
GitHub

Blending (C-defined module functions)

compose_blend_mode(src_color_factor, dst_color_factor, color_op, src_alpha_factor, dst_alpha_factor, alpha_op)

Create a custom blend mode for use with Texture#blend_mode=.

The blend equations are: dstRGB = color_op(srcRGB * src_color_factor, dstRGB * dst_color_factor) dstA = alpha_op(srcA * src_alpha_factor, dstA * dst_alpha_factor)

Factors (Symbol): - :zero, :one - :src_color, :one_minus_src_color - :src_alpha, :one_minus_src_alpha - :dst_color, :one_minus_dst_color - :dst_alpha, :one_minus_dst_alpha

Operations (Symbol): - :add — src dst (all renderers) - :subtract — src - dst - :rev_subtract — dst - src - :minimum — min(src, dst) - :maximum — max(src, dst)+

Parameters
  • src_color_factor Symbol — multiplier for source RGB
  • dst_color_factor Symbol — multiplier for destination RGB
  • color_op Symbol — operation combining color components
  • src_alpha_factor Symbol — multiplier for source alpha
  • dst_alpha_factor Symbol — multiplier for destination alpha
  • alpha_op Symbol — operation combining alpha components

Returns Integer — opaque blend mode ID for Texture#blend_mode=

Example
# Inverse/invert effect (text shows opposite of background)
inverse = Teek::SDL2.compose_blend_mode(
  :one_minus_dst_color, :one_minus_src_alpha, :add,
  :zero, :one, :add
)
white_text = font.render_text("Hello", 255, 255, 255)
white_text.blend_mode = inverse
See also
View source ▼ 
static VALUE
sdl2_compose_blend_mode(VALUE self,
                        VALUE src_color, VALUE dst_color, VALUE color_op,
                        VALUE src_alpha, VALUE dst_alpha, VALUE alpha_op)
{
    SDL_BlendMode bm = SDL_ComposeCustomBlendMode(
        sym_to_blend_factor(src_color),
        sym_to_blend_factor(dst_color),
        sym_to_blend_operation(color_op),
        sym_to_blend_factor(src_alpha),
        sym_to_blend_factor(dst_alpha),
        sym_to_blend_operation(alpha_op)
    );
    return INT2NUM((int)bm);
}
GitHub

register_event_source(interval_ms: 16)

Register SDL2 as a Tcl event source. Called automatically when the first Viewport is created. Uses a C function pointer for the hot path — no Ruby in the poll loop.

Parameters
  • interval_ms Integer — polling interval in milliseconds

Returns void

@api private

View source ▼ 
def self.register_event_source(interval_ms: 16)
  return if @event_source&.registered?

  fn_ptr = _event_check_fn_ptr   # C function address from sdl2bridge.c
  @event_source = Teek._register_event_source(fn_ptr, 0, interval_ms)
end
GitHub

unregister_event_source

Remove SDL2 from Tcl’s event loop. Called automatically when the last Viewport is destroyed.

Returns void

@api private

View source ▼ 
def self.unregister_event_source
  @event_source&.unregister
  @event_source = nil
end
GitHub
Instance Methods ↑

channels

Number of audio channels (1 = mono, 2 = stereo).

Returns Integer

clear

Flush all queued audio data.

Returns nil

destroy

Close the audio device. Further method calls will raise.

Returns nil

destroyed?

Whether the audio stream has been destroyed.

Returns Boolean

format

Audio sample format.

Returns Symbol — :s16, :f32, or :u8

frequency

Sample rate in Hz.

Returns Integer

initialize(frequency: 44100, format: :s16, channels: 2)

Open a push-based audio output device. The stream starts paused — call #resume after queuing initial data.

Parameters
  • frequency Integer — sample rate in Hz (default: 44100)
  • format Symbol — sample format — :s16 (signed 16-bit), :f32 (32-bit float), or :u8 (unsigned 8-bit)
  • channels Integer — 1 for mono, 2 for stereo (default: 2)

measure(text)

Measure the pixel dimensions the text would occupy when rendered. Does not create a texture — useful for layout calculations.

Parameters
  • text String — the text to measure (UTF-8)

Returns Array(Integer, Integer) — [width, height]

pause

Pause audio playback. Queued data is preserved.

Returns nil

playing?

Whether the audio device is currently playing (not paused).

Returns Boolean

queue(data)

Push raw PCM data to the audio device. The data must be a binary String whose format matches the stream’s format and channels (e.g. packed signed 16-bit integers for :s16).

Parameters
  • data String — raw PCM samples (binary encoding)

Returns nil

queued_bytes

Bytes of audio data currently queued for playback.

Returns Integer

queued_samples

Number of audio sample frames currently queued. One sample frame = one value per channel. Useful for pacing audio generation (e.g. keep 2000–4000 samples buffered).

Returns Integer

render_text(text, r, g, b, a 255, premultiply false)

Render a string to a new Texture using TTF_RenderUTF8_Blended. The texture has the exact pixel dimensions of the rendered text.

When premultiply is true, each pixel’s RGB is multiplied by its alpha before creating the texture. This is required for custom blend modes (from SDL2.compose_blend_mode) that read source RGB independently of source alpha — without it, the “transparent” background of the text surface retains the foreground color, causing the entire texture rect to be visible.

Parameters
  • text String — the text to render (UTF-8)
  • r Integer — red (0–255)
  • g Integer — green (0–255)
  • b Integer — blue (0–255)
  • a Integer — alpha (0–255)
  • premultiply Boolean — premultiply alpha for custom blend modes

Returns Texture — a new texture containing the rendered text

See also

resume

Start or unpause audio playback.

Returns nil

Members: Classes (9)