Creates an embedded OpenGL sub-canvas. It exists only inside an IupGLCanvasBox.
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 to be a direct child of the IupGLCanvasBox. It can be place 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.
Ihandle* IupGLSubCanvas(void); [in C]
iup.glsubcanvas{} -> (elem: ihandle) [in Lua]
glsubcanvas() [in LED]
Returns: the identifier of the created element, or NULL if an error occurs.
ACTIVE: disables mouse interaction and highlight feedback. Also for some controls it will affect its appearance to greyed version. Possible values: "YES, "NO". Default: "YES".
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 in OpenGL using the Freetype library. Depends on locating a font file that matches the font attribute. See Notes bellow. 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 supports 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.
SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, TIP, SIZE, RASTERSIZE, VISIBLE: also accepted.
GL_ACTION: Action generated when the sub-canvas needs to be redrawn. The transformation matrix is already set to the subcanvas rectangular region. Also, do not call IupGLMakeCurrent nor IupGLSwapBuffers, the IupCanvasBox management will take care of that.
int function(Ihandle *ih); [in C]
elem:gl_action() -> (ret: number) [in Lua]
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.
MAP_CB, UNMAP_CB, DESTROY_CB: common callbacks are supported.
Since there is no high quality text rendering in OpenGL we use FTGL and Freetype to load fonts and render using OpenGL. So we also export the same function used internally so the applications can have the same functionality for other purposes, among with other utilities for text and images.
void IupGLDrawText(Ihandle* ih, const char* str, int len, int x, int y); [in C] iup.GLDrawText(ih: ihandle, str: string, x, y: number) [in Lua] ih:GLDrawText(str: string, x, y: number) [in Lua]
Draws a text in the given position using the current FONT. The size of the string is used only in C. Can be -1 so strlen is used internally. The coordinates are relative the top-left corner of the text. ATTENTION: Different from the IupDrawText function, the color of the text uses the current color set in the OpenGL context.
void IupGLDrawImage(Ihandle* ih, const char* name, int x, int y, int active); [in C] iup.GLDrawImage(ih: ihandle, name: string or image: ihandle, x, y, active: number) [in Lua] ih:GLDrawImage(name: string or image: ihandle, x, y, active: number) [in Lua]
Draws an image given its name. The coordinates are relative the top-left corner of the image. The image name follows the same behavior as the IMAGE attribute used by many controls. Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage. In Lua, the name parameter can be the actual image handle. When active parameter is 0, it will draw the same image in inactive state.
void IupGLDrawGetTextSize(Ihandle* ih, const char* str, int *w, int *h); [in C] iup.GLDrawGetTextSize(ih: ihandle, str: string) -> w, h: number [in Lua] ih:GLDrawGetTextSize(str: string) -> w, h: number [in Lua]
Returns the given text size using the current FONT. In C unwanted values can be NULL.
void IupGLDrawGetImageInfo(const char* name, int *w, int *h, int *bpp); [in C] iup.GLDrawGetImageInfo(name: string) -> w, h, bpp: number [in Lua] ih:GLDrawGetImageInfo(name: string) -> w, h, bpp: number [in Lua]
Returns the given image size and bits per pixel. bpp can be 8, 24 or 32. In C unwanted values can be NULL.
FTGL and Freetype are third party libraries not developed at Tecgraf. But their licenses are also free and have the same freedom as the Tecgraf Library License. You can read the license and copyright in the files ftgl.txt and freetype.txt. 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.
- search for the font in the system. In Windows use the Registry to locate the font, in UNIX use the FontConfig library;
- use the type face as a file title, compose with the font path to get a filename (assume style already in the typeface);
- try some pre-defined names, and use the style to compose the filename;
- 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.