OpenGLGadget()

Syntax

Result = OpenGLGadget(#Gadget, x, y, Width, Height [, Flags])
Description
Creates an OpenGL gadget in the current GadgetList. This gadget provides an OpenGL drawing context and events for mouse and keyboard interaction to easily create 3D opengl view. Most of the OpenGL commands are directly available in PureBasic using the underscore API notation (command ending with an underscore, like 'glBegin_()').

Parameters

#Gadget A number to identify the new gadget. #PB_Any can be used to auto-generate this number.
x, y, Width, Height The position and dimensions of the new gadget (in pixels). The maximum width and height is 16000 pixels.
Flags (optional) Flags to modify the gadget behavior. It can be a combination of the following constants: 
  #PB_OpenGL_Keyboard               : allows the gadget to receive the keyboard focus and keyboard events.
  #PB_OpenGL_NoFlipSynchronization  : disables the vsync synchronization.
  #PB_OpenGL_FlipSynchronization    : enables the vsync synchronization (default).
  #PB_OpenGL_NoDepthBuffer          : disables the depth buffer.
  #PB_OpenGL_16BitDepthBuffer       : creates a 16-bit depth buffer (default).
  #PB_OpenGL_24BitDepthBuffer       : creates a 24-bit depth buffer.
  #PB_OpenGL_NoStencilBuffer        : disables the stencil buffer (default).
  #PB_OpenGL_8BitStencilBuffer      : creates a 8-bit stencil buffer.
  #PB_OpenGL_NoAccumulationBuffer   : disables the accumulation buffer (default).
  #PB_OpenGL_32BitAccumulationBuffer: creates a 32-bit accumulation buffer.
  #PB_OpenGL_64BitAccumulationBuffer: creates a 64-bit accumulation buffer.
The #PB_OpenGL_Keyboard flag is required to receive any keyboard events in the gadget. If you include this flag, you should check for the #PB_EventType_Focus and #PB_EventType_LostFocus events and draw a visual indication on the gadget when it has the focus so it is clear to the user which gadget currently has the focus.

Return value

Returns nonzero on success and zero on failure. If #PB_Any was used as the #Gadget parameter then the return-value is the auto-generated gadget number on success.

Remarks

The created gadget starts out with just a black background. The current OpenGL context is set to this new created gadget. To change the current OpenGL context, use the #PB_OpenGL_SetContext attribute. Once drawn, a frame can be displayed using the #PB_OpenGL_FlipBuffers attribute.

As the OpenGL gadget is meant to be a realtime rendering gadget, it doesn't store its current rendering in a seperate buffer: it needs to be rendered again when the window is resized, minimized, maximized or if the gadget itself is resized or moved.

The following events are reported by the gadget. The EventType() function reports the type of the current gadget event: 
  #PB_EventType_MouseEnter      : The mouse cursor entered the gadget
  #PB_EventType_MouseLeave      : The mouse cursor left the gadget
  #PB_EventType_MouseMove       : The mouse cursor moved
  #PB_EventType_MouseWheel      : The mouse wheel was moved
  #PB_EventType_LeftButtonDown  : The left mouse button was pressed
  #PB_EventType_LeftButtonUp    : The left mouse button was released
  #PB_EventType_LeftClick       : A click with the left mouse button
  #PB_EventType_LeftDoubleClick : A double-click with the left mouse button
  #PB_EventType_RightButtonDown : The right mouse button was pressed
  #PB_EventType_RightButtonUp   : The right mouse button was released
  #PB_EventType_RightClick      : A click with the right mouse button
  #PB_EventType_RightDoubleClick: A double-click with the right mouse button
  #PB_EventType_MiddleButtonDown: The middle mouse button was pressed
  #PB_EventType_MiddleButtonUp  : The middle mouse button was released
  #PB_EventType_Focus           : The gadget gained keyboard focus
  #PB_EventType_LostFocus       : The gadget lost keyboard focus
  #PB_EventType_KeyDown         : A key was pressed
  #PB_EventType_KeyUp           : A key was released
  #PB_EventType_Input           : Text input was generated
Note that the events #PB_EventType_KeyDown, #PB_EventType_KeyUp and #PB_EventType_Input are only reported when the gadget has the keyboard focus. This means that the #PB_OpenGL_Keyboard flag has to be set on gadget creation to allow keyboard events. On Windows, the #PB_EventType_MouseWheel event is also only reported if the gadget has keyboard focus. On the other OS, this event is reported to the gadget under the cursor, regardless of keyboard focus.

Further information about the current event can be received with the GetGadgetAttribute() function. This information is only available if the current event received by WaitWindowEvent() or WindowEvent() is an event for this gadget. The following attributes can be used:

#PB_OpenGL_MouseX, #PB_OpenGL_MouseY
Returns the given mouse coordinate relative to the drawing area of the gadget. This returns the mouse location at the time that the event was generated, so the result can differ from the coordinates reported by WindowMouseX() and WindowMouseY() which return the current mouse location regardless of the state of the processed events. The coordinates returned using these attributes should be used for this gadget to ensure that the mouse coordinates are in sync with the current event.
#PB_OpenGL_Buttons
Returns the state of the mouse buttons for the event. The result is a combination (using bitwise or) of the following values: 
  #PB_OpenGL_LeftButton  : The left button is currently down.
  #PB_OpenGL_RightButton : The right button is currently down.
  #PB_OpenGL_MiddleButton: The middle button is currently down.
#PB_OpenGL_Modifiers
Returns the state of the keyboard modifiers for the event. The result is a combination (using bitwise or) of the following values: 
  #PB_OpenGL_Shift  : The 'shift' key is currently pressed.
  #PB_OpenGL_Alt    : The 'alt' key is currently pressed.
  #PB_OpenGL_Control: The 'control' key is currently pressed.
  #PB_OpenGL_Command: The 'command' (or "apple") key is currently pressed. (Mac OSX only)
#PB_OpenGL_WheelDelta
Returns the movement of the mouse wheel in the current event in multiples of 1 or -1. A positive value indicates that the wheel was moved up (away from the user) and a negative value indicates that the wheel was moved down (towards the user). This attribute is 0 if the current event is not a #PB_EventType_MouseWheel event.
#PB_OpenGL_Key
Returns the key that was pressed or released in a #PB_EventType_KeyDown or #PB_EventType_KeyUp event. The returned value is one of the #PB_Shortcut_... values used by the AddKeyboardShortcut() function. This attribute returns raw key presses. To get text input for the gadget, it is better to watch for #PB_EventType_Input events and use the #PB_OpenGL_Input attribute because it contains the text input from multiple key presses such as shift or dead keys combined.
#PB_OpenGL_Input
Returns the input character that was generated by one or more key presses. This attribute is only present after a #PB_EventType_Input event. The returned character value can be converted into a string using the Chr() function.
In addition to this event information, GetGadgetAttribute() can also be used to read the following attributes:

#PB_OpenGL_Cursor
Returns the cursor that is currently used in the gadget. See below for a list of possible values. If the gadget is using a custom cursor handle, the return-value is -1.
#PB_OpenGL_CustomCursor
Returns the custom cursor handle that was set using SetGadgetAttribute(). If the gadget uses a standard cursor, the return-value is 0.
The SetGadgetAttribute() function can be used to modify the following gadget attributes

#PB_OpenGL_SetContext
Changes the current OpenGL context to this gadget context. 
  #True  : use the OpenGL context from this gadget.
  #False : remove the current OpenGL context. No more context are available.
#PB_OpenGL_FlipBuffers
Flip the back and front buffers. All drawing are done in the back buffer. To be visible, the buffers needs to be flipped, so the back becomes the front one (the one which is displayed). 
  #True  : flips the buffers
  #False : don't flip the buffers (no use for now).
#PB_OpenGL_Cursor
Changes the cursor that is displayed when the mouse is over the gadget. The following values are possible: 
  #PB_Cursor_Default        : default arrow cursor
  #PB_Cursor_Cross          : crosshair cursor
  #PB_Cursor_IBeam          : I-cursor used for text selection
  #PB_Cursor_Hand           : hand cursor
  #PB_Cursor_Busy           : hourglass or watch cursor
  #PB_Cursor_Denied         : slashed circle or X cursor
  #PB_Cursor_Arrows         : arrows in all direction (not available on Mac OSX)
  #PB_Cursor_LeftRight      : left and right arrows
  #PB_Cursor_UpDown         : up and down arrows
  #PB_Cursor_LeftUpRightDown: diagonal arrows (Windows only)
  #PB_Cursor_LeftDownRightUp: diagonal arrows (Windows only)
  #PB_Cursor_Invisible      : hides the cursor
#PB_OpenGL_CustomCursor
Changes the cursor that is displayed when the mouse is over the gadget to a custom cursor handle created using the corresponding OS API. This attribute expects the following kind of input:
Windows: a HCURSOR handle
Linux: a GtkCursor pointer
Mac OSX: a pointer to a Cursor structure
A 'mini help' can be added to this gadget using GadgetToolTip().

Example

OpenGLGadget.pb

See Also

GetGadgetAttribute(), SetGadgetAttribute(), EventType()

Supported OS

All

<- MDIGadget() - Gadget Index - OpenGadgetList() ->