NAME

AntTweakBar - Perl bindings for AntTweakBar

SYNOPSIS

  use AntTweakBar qw/:all/;
  use SDL::Events;

  # Setup part: link AntTweakBar with your OpenGL/SDL system

  AntTweakBar::init(TW_OPENGL);
  AntTweakBar::window_size($width, $height);

  # in your main rendering routine
  sub display {
    AntTweakBar::draw;
  }

  sub process_events {
    SDL::Events::pump_events;
    my $event = $self->sdl_event;
    while (SDL::Events::poll_event($event)) {
        ...;
        AntTweakBar::eventSDL($event);
    }
  }


  # define bars with variables
  my $bar = AntTweakBar->new(
    "TweakBar & Perl",
    size  => '200 400',
    color => '96 216 224'
  );
  my $enabled = 0;
  $bar->add_variable(
    mode       => 'rw',
    name       => "Enabled",
    type       => 'bool',
    value      => \$enabled
);

DESCRIPTION

AntTweakBar (see http://anttweakbar.sourceforge.net/) is nice tiny GUI library for OpenGL/SDL/DirectX applications.

If you are in hurry to evaluate it then intall AntTweakBar and try examples from eg directory within the distribution.

To display AntTweakBar in your OpenGL/SDL application you should do the following:

intialize AntTweakBar(s):
  AntTweakBar::init(TW_OPENGL);
  AntTweakBar::window_size($width, $height);
draw AntTweakBar(s):
  AntTweakBar::draw;
let AntTweakBar(s) respond to user interactions:
  AntTweakBar::eventSDL($event);
create AntTweakBar instance(s)
  my $bar = AntTweakBar->new("TweakBar");
add variables into the $bar
  my $value = 3.14;
  $bar->add_variable(
    mode       => 'rw',
    name       => "Enabled",
    type       => 'integer',
    value      => \$value
  );

See working examples in the eg directoctory within the distribution.

EXPORT

Constants only

CONSTANTS

The following constants let AntTweakBar know which graphic system do you use, to know how to render itself

TW_OPENGL

Render using plain old OpenGL

TW_OPENGL_CORE

Render AntTweakBar using OpenGL core profile, which excludes deprecated OpenGL functions. See: https://en.wikipedia.org/wiki/OpenGL_4#OpenGL_3.2

TW_DIRECT3D9 (not implemented)

TW_DIRECT3D10 (not implemented)

TW_DIRECT3D11 (not implemented)

METHODS

new

  my $bar = AntTweakBar->new(
    "TweakBar & Perl",
    size  => '200 400',
    color => '96 216 224'
  );

  my $another_bar = AntTweakBar->new(
    "Misc.",
  );

Creates new AntTweakBar instance. Optionally the list of strings of bar-related parameters can be provided. See the list of available at http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:twbarparamsyntax.

add_button

  $bar->add_button(
    name       => 'my_btn',
    cb         => sub { say "clicked!" },
    definition => "label='Click me!'",    # optional
  );

  $bar->add_button(
    name       => 'my_btn',
    cb         => sub { say "clicked!" },
    definition => { # optional
      label => 'Click me!'
    }
  );

The definition parameters are the same as for variable. See http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:varparamsyntax#parameters.

add_separator

  $bar->add_separator('separator-name');

add_variable

  my $zoom = 1.0;
  $bar->add_variable(
    mode       => 'rw',
    name       => "Zoom",
    type       => 'number',
    value      => \$zoom,
    definition => " min=0.01 max=2.5 step=0.01 help='Bla-bla-bla.' ",
  );

  # the same, but with more perlish style in definition
  $bar->add_variable(
    mode       => 'rw',
    name       => "Zoom",
    type       => 'number',
    value      => \$zoom,
    definition => {
        min     => "0.01",
        max     => "2.5",
        step    => "0.01",
        keyIncr => 'z',
        keyDecr => 'Z',
        help    => 'Scale the object (1=original size).'
    },
  );

  my $bool = undef;
  $bar->add_variable(
    mode       => 'rw',
    name       => "bool_rw_cb",
    type       => 'bool',
    cb_read    => sub { $bool; },
    cb_write   => sub {
        $bool = shift;
        say "writing value $bool";
    }
  );

mode, name, type are mandatory. Either value or cb_read should be specified. The definition and cb_write are optional.

mode

The mode can be rw (read/write) or ro (read only). The mode specified whether the variable value could be modified via AntTweakBar.

name

Defines the unique variable name at tweakbar. Unless label is specified via defintion, then name also defines the visual label. for the variable.

type

Defines the type of variable. Original types http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:twtype were reduced to:

bool
integer
number (float)
string
color3f

variable must be reference to array, consisted of 3 float values: rgb.

color4f

variable must be reference to array, consisted of 4 float values: rgba.

direction

3D-vector (direction). The variable must be reference to array, consisted of 3 float values.

quaternion

4D-vector (3D-object rotation). The variable must be reference to array, consisted of 4 float values.

custom type of Anttweakbar::Type

value

The reference to the variable value. For complex types (e.g. quaternion) it must also be an reference to array of 3 numbers.

cb_read

Closure, that returns the actual value of variable.

cb_write($value)

Closure, that is been invoked when user sets new value to the variable. If cb_write is undefined, then the variable considered readonly.

definition

An string or hashref of values that allows additional tuning of variable in Anttweakbar. See http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:varparamsyntax#parameters for possible values.

remove_variable($name)

  $bar->remove_variable('Zoom');

refresh

  $bar->refresh;

Tells Anttweakbar that variable values are possibly changed and should be updated.

set_bar_params(%values)

  $bar->set_bar_params(
    size        => '350 700,
    valueswidth => '200'
    visible     => 'false',
  );

Updates bar definition at runtime. See http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:twbarparamsyntax.

set_variable_params($var_name, $var_definition)

  $bar->set_variable_params('ObjRotation', readonly => 'true');

Updates variable definition at runtime. See http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:varparamsyntax#parameters

INITIALIZATION AND DRAW FUNCTIONS

init

  AntTweakBar::init(TW_OPENGL);

Initializes AntTweakBar

terminate

  AntTweakBar::terminate

Uninitializes AntTweakBar

window_size

  AntTweakBar::window_size(640, 480);

Tell AntTweakBar the actual size of your window

draw

  AntTweakBar::draw;

Draw AntTweakBar just before the frame buffer is presented (swapped).

OPENGL EVENT FUNCTIONS

eventMouseButtonGLUT

  glutMouseFunc(\&AntTweakBar::eventMouseButtonGLUT);

Let AntTweakBar handles mouse button clicks

eventMouseMotionGLUT

  glutMotionFunc(\&AntTweakBar::eventMouseMotionGLUT);
  glutPassiveMotionFunc(\&AntTweakBar::eventMouseMotionGLUT);

Let AntTweakBar handles mouse movements with pressed button(s) and passive mouse movements

eventKeyboardGLUT

  glutKeyboardFunc(\&AntTweakBar::eventKeyboardGLUT);

Let AntTweakBar handles key presses

eventSpecialGLUT

  glutSpecialFunc(\&AntTweakBar::eventSpecialGLUT);

GLUTModifiersFunc

  AntTweakBar::GLUTModifiersFunc(\&glutGetModifiers);

SDL EVENT FUNCTION

eventSDL

If you use SDL than it is more simple to let AntTweakBar process all input-related events via single call:

  AntTweakBar::eventSDL($sdl_event);

SEE ALSO

Alien::AntTweakBar, SDL, OpenGL, http://anttweakbar.sourceforge.net/

AUTHOR

Ivan Baidakou <dmol@(gmx.com)>

CREDITS

    David Horner

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Ivan Baidakou

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.20.0 or, at your option, any later version of Perl 5 you may have available.