AllegroGL: Allegro-compatible GUI routines

# Allegro-compatible GUI routines

AllegroGL GUI wrappers. More...

## Functions

- int algl_do_dialog (DIALOG *dialog, int focus_obj)
    AllegroGL-friendly version of do_dialog.
- int algl_popup_dialog (DIALOG *dialog, int focus_obj)
    AllegroGL-friendly version of popup_dialog.
- void algl_draw_mouse (void)
    Draws a mouse pointer on the screen.
- void algl_set_mouse_drawer (void(*user_draw_mouse)(void))
    Sets (or clears) a user mouse drawing callback.
- int algl_alert (AL_CONST char *s1, AL_CONST char *s2, AL_CONST char *s3, AL_CONST char *b1, AL_CONST char *b2, int c1, int c2)
    AllegroGL-friendly version of Allegro's alert.
- int algl_alert3 (AL_CONST char *s1, AL_CONST char *s2, AL_CONST char *s3, AL_CONST char *b1, AL_CONST char *b2, AL_CONST char *b3, int c1, int c2, int c3)
    AllegroGL-friendly version of Allegro's alert3.
- int d_algl_viewport_proc (int msg, DIALOG *d, int c)
    Creates a viewport object where OpenGL commands can be performed.

## Detailed Description

AllegroGL GUI wrappers.

Due to several specificities of OpenGL, some of the Allegro's GUI routines can not be used "as is". Indeed they are not designed to natively support double-buffered graphics mode. Hence AllegroGL provides wrapper routines of do_dialog, alert and so on...

AllegroGL GUI routines internally call allegro_gl_set_allegro_mode() and its counterpart allegro_gl_unset_allegro_mode(). So the default drawing mode in the GUI routines is the "2D Allegro mode" and functions like line() or rect() can safely be called.

Additionnaly AllegroGL provides a new GUI object d_algl_viewport_proc() which allows to have a 3D viewport that can safely coexist with other "classical" 2D GUI objects : no need to call allegro_gl_set_allegro_mode() or to save the current state of OpenGL.

## Function Documentation

int algl_do_dialog | ( | DIALOG * | dialog,
|  | int | focus_obj |
| ) |  |  |

AllegroGL-friendly version of do_dialog.

This behaves exactly like do_dialog but forces a screen clear, rerender, and flip, after each iteration of update_dialog.

User gui components can do OpenGL or Allegro rendering to draw themselves. They should take care not to alter any OpenGL state (or be aware that this will affect other components). For the main render, they will be called in order, but this is not guarranteed at other times -- they may be called out of order; however the results will never be visible, so just don't crash.

Before drawing the final (in-order) pass, the color and depth buffers will be cleared -- set your clear color to black or green or whatever you like. You can overdraw it with an object of course.

Further notes: This routine uses allegro_gl_set_allegro_mode(), so your GUI components can use allegro_gl_unset_allegro_mode() to restore the old state while they draw themselves, provided that they use allegro_gl_set_allegro_mode() again afterwards.

Parameters:

  | dialog | an array of dialog objects terminated by one with a NULL dialog procedure.
  | focus_obj | index of the object on which the focus is set (-1 if you don't want anything to have the focus

See also:
  algl_draw_mouse

Definition at line 58 of file gui.c.

References allegro_gl_set_allegro_mode(), and allegro_gl_unset_allegro_mode().

int algl_popup_dialog | ( | DIALOG * | dialog,
|  | int | focus_obj |
| ) |  |  |

AllegroGL-friendly version of popup_dialog.

This routine is likely to be very slow. It has to take a copy of the screen on entry, then where algl_do_dialog() would just clear the screen, this routine has to blit that copy back again after clearing. This is the only way to do overlays without knowing what type of flipping is going on.

Also, note that we don't save the depth buffer or anything like that so don't go around thinking that algl_popup_dialog won't affect anything when it's gone.

So, unless you need overlays, it's recommended that you just use algl_do_dialog(), and if you do need overlays, it's recommended that you just use algl_do_dialog() and redraw the thing you're overlaying yourself. If you're lazy or that's impossible, use this routine...

Parameters:

  | dialog | an array of dialog objects terminated by one with a NULL dialog procedure.
  | focus_obj | index of the object on which the focus is set (-1 if you don't want anything to have the focus

See also:
  algl_do_dialog, algl_draw_mouse

Definition at line 111 of file gui.c.

References algl_draw_mouse(), allegro_gl_flip(), allegro_gl_set_allegro_mode(), and allegro_gl_unset_allegro_mode().

Referenced by algl_alert3().

void algl_draw_mouse | ( | void |  | ) |

Draws a mouse pointer on the screen.

This function draws a mouse pointer on the screen. By default, it displays Allegro's standard black arrow cursor. However the settings of the cursor can be altered by Allegro's functions for mouse cursor management like show_mouse, set_mouse_sprite, scare_mouse, and so on... As a consequence, it should be stressed that if show_mouse(NULL) is called then algl_draw_mouse() won't draw anything.

Unlike Allegro, AllegroGL does not manage the mouse cursor with an interrupt routine, hence algl_draw_mouse() must be regularly called in order to display the mouse cursor (ideally it should be the last function called before allegro_gl_flip()). However if you use algl_do_dialog() then you do not need to make explicit calls to algl_draw_mouse() since algl_do_dialog() takes care of that for you.

See also:
  algl_set_mouse_drawer

Definition at line 187 of file gui.c.

Referenced by algl_popup_dialog(), and d_algl_viewport_proc().

void algl_set_mouse_drawer | ( | void(*)(void) | user_draw_mouse | ) |

Sets (or clears) a user mouse drawing callback.

This function allows to use a user-defined routine to display the mouse cursor. This allows nice effects like a spinning cube or any fancy thing you can think of to be used as a mouse cursor.

When a user mouse drawing callback is enabled, set_mouse_sprite has no effect. However show_mouse and scare_mouse are still enabled.

Parameters:

  | user_draw_mouse | user routine that displays the mouse cursor (NULL if you want to get back to the standard behaviour)

See also:
  algl_draw_mouse

Definition at line 284 of file gui.c.

int algl_alert | ( | AL_CONST char * | s1,
|  | AL_CONST char * | s2,
|  | AL_CONST char * | s3,
|  | AL_CONST char * | b1,
|  | AL_CONST char * | b2,
|  | int | c1,
|  | int | c2 |
| ) |  |  |

AllegroGL-friendly version of Allegro's alert.

Displays a simple alert box, containing three lines of text (s1-s3), and with either one or two buttons. The text for these buttons is passed in b1 and b2 (b2 may be null), and the keyboard shortcuts in c1 and c2. Returns 1 or 2 depending on which button was selected.

Definition at line 449 of file gui.c.

References algl_alert3().

int algl_alert3 | ( | AL_CONST char * | s1,
|  | AL_CONST char * | s2,
|  | AL_CONST char * | s3,
|  | AL_CONST char * | b1,
|  | AL_CONST char * | b2,
|  | AL_CONST char * | b3,
|  | int | c1,
|  | int | c2,
|  | int | c3 |
| ) |  |  |

AllegroGL-friendly version of Allegro's alert3.

Displays a simple alert box, containing three lines of text (s1-s3), and with either one, two, or three buttons. The text for these buttons is passed in b1, b2, and b3 (NULL for buttons which are not used), and the keyboard shortcuts in c1 and c2. Returns 1, 2, or 3 depending on which button was selected.

Definition at line 329 of file gui.c.

References algl_popup_dialog().

Referenced by algl_alert().

int d_algl_viewport_proc | ( | int | msg,
|  | DIALOG * | d,
|  | int | c |
| ) |  |  |

Creates a viewport object where OpenGL commands can be performed.

The viewport and the scissor are updated so that this GUI object behaves somewhat like a window. The dp field of the DIALOG object points to a callback function : int (*callback)(BITMAP* viewport, int msg, int c) where: viewport is a sub-bitmap of the screen limited to the area of the DIALOG object. msg and c are the values that come from the GUI manager. The callback function must return a sensible value to the GUI manager like D_O_K if everything went right or D_EXIT to close the dialog.

Definition at line 477 of file gui.c.

References algl_draw_mouse(), allegro_gl_flip(), allegro_gl_set_allegro_mode(), and allegro_gl_unset_allegro_mode().