/ 
IUP-0.305
River stage zero No dependents
/ IUP::CanvasGL

NAME

IUP::CanvasGL - [GUI element] 2D canvas based on OpenGL (co-operates with OpenGL module)

DESCRIPTION

Creates an OpenGL canvas (drawing area for OpenGL).

IMPORTANT: For using IUP::CanvasGL you also need to have module OpenGL installed.

Example:

use IUP ':all';
use OpenGL ':all';

Callback handler prototype:

sub action_callback {
  my ($self, $x, $y) = @_;
  $self->GLMakeCurrent();
  glViewport(0, 0, 300, 300);
  glClearColor(1.0, 1.0, 1.0, 1.0);
  glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
  glColor3f(1.0,0.0,0.0);
  glBegin(GL_QUADS); 
    glVertex2f( 0.9,  0.9); 
    glVertex2f( 0.9, -0.9); 
    glVertex2f(-0.9, -0.9); 
    glVertex2f(-0.9,  0.9); 
  glEnd();
  $self->GLSwapBuffers();
  return IUP_DEFAULT;
}

my $dlg = IUP::Dialog->new( 
            TITLE=>"Example",
            MINSIZE=>"300x300",
            child=>IUP::CanvasGL->new( BUFFER=>"DOUBLE", RASTERSIZE=>"300x300", ACTION=>\&action_callback ),
          );

$dlg->Show();
IUP->MainLoop();

USAGE

CREATION - new() method

my $canvas_gl = IUP::CanvaGL->new( BUFFER=>"DOUBLE", RASTERSIZE=>"300x300" );

Returns: the identifier of the created element, or undef if an error occurs.

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

The IUP::CanvasGL element handles all attributes defined for a conventional canvas, see IUP::Canvas.

Apart from these attributes, IUP::CanvasGL handles specific attributes used to define the kind of buffer to be instanced. Such attributes are all creation only attributes and must be set before the element is mapped on the native system. After the mapping, specifying these special attributes has no effect.

ACCUM_RED_SIZE, ACCUM_GREEN_SIZE, ACCUM_BLUE_SIZE and ACCUM_ALPHA_SIZE

Indicate the number of bits for representing the color components in the accumulation buffer. Value 0 means the accumulation buffer is not necessary. Default is 0.

ALPHA_SIZE

Indicates the number of bits for representing each colors alpha component (valid only for RGBA and for hardware that store the alpha component). Default is "0".

BUFFER

Indicates if the buffer will be single "SINGLE" or double "DOUBLE". Default is "SINGLE".

BUFFER_SIZE

Indicates the number of bits for representing the color indices (valid only for INDEX). The system default is 8 (256-color palette).

COLOR

Indicates the color model to be adopted: "INDEX" or "RGBA". Default is "RGBA".

COLORMAP

(read-only)

Returns "Colormap" in UNIX and "HPALETTE" in Win32, if COLOR=INDEX.

CONTEXT

(read-only)

Returns "GLXContext" in UNIX and "HGLRC" in Win32.

DEPTH_SIZE

Indicates the number of bits for representing the z coordinate in the z-buffer. Value 0 means the z-buffer is not necessary.

ERROR

(read-only)

If an error is found, returns a string containing a description of the error in English.

RED_SIZE, GREEN_SIZE and BLUE_SIZE

Indicate the number of bits for representing each color component (valid only for RGBA). The system default is usually 8 for each component (True Color support).

REFRESHCONTEXT (write-only) [Windows Only]

Action attribute to refresh the internal device context when it is not owned by the window class. The IUP::Canvas of the Win32 driver will always create a window with an owned DC, but GTK in Windows will not.

STENCIL_SIZE

Indicates the number of bits in the stencil buffer. Value 0 means the stencil buffer is not necessary. Default is 0.

STEREO

Creates a stereo GL canvas (special glasses are required to visualize it correctly). Possible values: "YES" or "NO". Default: "NO".

SHAREDCONTEXT

Name of another IUP::GLCanvas that will share its display lists and textures. That canvas must be mapped before this canvas.

VISUAL

(read-only)

Returns "XVisualInfo*" in UNIX and "HDC" in Win32.

CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:

The IUP::CanvasGL element understands all callbacks defined for a conventional canvas, see IUP::Canvas section callbacks.

Additionally:

RESIZE_CB

Callback handler prototype:

sub resize_cb_handler {
  my ($self, $width, $heght) = @_;
  #...
}

By default the resize callback sets:

glViewport(0,0,$width,height);

Auxiliary Functions

These are auxiliary functions based on the WGL and XGL extensions. Check the respective documentations for more information.

GLMakeCurrent()

$canvas_gl->GLMakeCurrent();

Activates the given canvas as the current OpenGL context. All subsequent OpenGL commands are directed to such canvas.

GLIsCurrent()

$canvas_gl->GLIsCurrent();

Returns a non zero value if the given canvas is the current OpenGL context.

GLSwapBuffers()

$canvas_gl->GLSwapBuffers();

Makes the BACK buffer visible. This function is necessary when a double buffer is used.

GLPalette()

$canvas_gl->GLPalette($index, $r, $g, $b);

Defines a color in the color palette. This function is necessary when INDEX color is used.

GLUseFont()

$canvas_gl->GLUseFont($first, $count, $list_base);

Creates a bitmap display list from the current FONT attribute. See the documentation of the wglUseFontBitmaps and glXUseXFont functions.

GLWait()

$canvas_gl->GLWait($gl);

If gl is non zero it will call glFinish or glXWaitGL, else will call GdiFlush or glXWaitX.

NOTES

In Windows XP, if the COMPOSITED attribute on the the main dialog (IUP::Dialog) is enabled then the hardware acceleration will be disabled.

The IUP::CanvasGL works with the GTK base driver in UNIX (X-Windows).

EXAMPLES

The element IUP::CanvasGL is used in the following sample scripts:

SEE ALSO

IUP::Canvas

The original doc: iupcanvasgl.html