IupGLSubCanvas

Definition: include pGUI.e

Ihandle ih = IupGLSubCanvas(string attributes="", sequence data={})
Description: Creates an embedded OpenGL sub-canvas. It exists only inside an IupGLCanvasBox.

For more information on the attributes and data parameters see IupSetAttributes.

This is an additional control that depends on the OpenGL library. It is included in the IupGLControls library.

It is a void element that does not map to a native canvas.
It mimics an IupCanvas with several attributes and callbacks in common, but everything is done inside a region of the IupGLCanvasBox.

The element does not have to be a direct child of the IupGLCanvasBox. It can be placed inside void containers like IupHbox, IupVbox, IupGridBox and so on.

This control is used as the base control for all visual elements of the IupGLControls library.

Returns: the identifier of the created element.
Notes: FTGL is used to draw text in OpenGL.
This is a third party library not developed at Tecgraf.
But its license is also free and have the same freedom as the Tecgraf Library License.
You can read the FTGL license and copyright in the technicalia dropdown below. FTGL is copyright to Henry Maddocks.

IUP uses the same FTGL library included in the CD library. Currently CD is using the FTGL version 2.1.3-rc5 with modifications.

To locate font files we use several strategies.

  1. search for the font in the system. In Windows use the Registry to locate the font, in UNIX use the FontConfig library;
  2. use the type face as a file title, compose with the font path to get a filename (assume style already in the typeface);
  3. try some pre-defined names, and use the style to compose the filename;
  4. use the typeface directly as the file name;
It will search for TrueType (*.ttf) and OpenType (*.otf) font files. It will search in the current directory; in the path returned by the FREETYPEFONTS_DIR environment variable or from the FREETYPEFONTS_DIR global attribute; and in Windows on the Fonts folder.

FTGL fonts are cached internally to optimal use of multiple fonts in the same IupGLCanvasBox.

We use OpenGL textures to draw images, so the image width and height MUST be a power of two if OpenGL version is 1.x, modern OpenGL does not have this limitation.
Attributes:
BGCOLOR background color used in derived controls. Can have an alpha component. Default: NULL.
BORDERCOLOR color used for borders in derived controls. Can have an alpha component. Default: "50 150 255".
BORDERWIDTH line width used for borders in derived controls. Default: "1". Any borders can be disabled by simply setting this value to 0.
CURSOR (non inheritable) Defines a cursor for the sub-canvas.
FONT Uses the FTGL library to render text. Depends on locating a font file that matches the font attribute. See Notes above.
The default font typeface is changed to Helvetica to avoid system fonts that are not well processed by FreeType.
HIGHLIGHT (non inheritable) flag indicating that the control is highlighted. Dynamically updated during mouse move.
HLCOLOR color used to indicate a highlight state in derived controls. Can have an alpha component. Default: "200 225 245".
PSCOLOR color used to indicate a press state in derived controls. Can have an alpha component. Default: "150 200 235".
PRESSED (non inheritable) flag indicating that the control is pressed with button1. Dynamically updated during button press.
REDRAWALL (non inheritable) flag to control the redraw update during a change of state like highlight or pressed.
If "No" only the element is redrawn, else all the IupGLCanvasBox is redrawn.
It will work only if the control is fully opaque. Default: "Yes".
REDRAWFRONT (non inheritable, write-only) redraw only the control on the front buffer. It will work only if the control is fully opaque.
UNDERLINE (non inheritable) flag indicating that the control text should be redrawn with an underline.
Since FTGL does not support underline, the drawing of the text will manually draw a line under the text.
WID (non inheritable) returns the same value as the IupGLCanvasBox where the element is inside.
ZORDER (non inheritable, write-only) change the order of the control inside its parent.
also ACTIVE, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, TIP, SIZE, RASTERSIZE, VISIBLE: also accepted.
Callbacks
GL_ACTION Action generated when the sub-canvas needs to be redrawn.

function gl_action_cb(Ihandle ih)
ih: identifier of the element that activated the event.
GL_BUTTON_CB Action generated when any mouse button is pressed or released.
Same parameters as BUTTON_CB.
If IUP_CONTINUE is returned the application callback is called even the user clicked on the sub-canvas.
GL_ENTERWINDOW_CB Action generated when the mouse enters the element. Same parameters as ENTERWINDOW_CB.
GL_LEAVEWINDOW_CB Action generated when the mouse leaves the element. Same parameters as LEAVEWINDOW_CB.
GL_MOTION_CB Action generated when the mouse is moved. Same parameters as MOTION_CB.
If IUP_CONTINUE is returned the application callback is called even the user moved the cursor on the sub-canvas.
GL_WHEEL_CB Action generated when the mouse wheel is rotated. Same parameters as WHEEL_CB.
If IUP_CONTINUE is returned the application callback is called even the user clicked on the sub-canvas.
also MAP_CB, UNMAP_CB, DESTROY_CB: common callbacks are supported.
See Also: IupCanvas, IupGLCanvas