Graphics Context Tutorial - EdgarReynaldo/EagleGUI GitHub Wiki

Graphics Context Tutorial

Welcome to the graphics context tutorial for Eagle. This tutorial covers basic window creation and display, as well as loading fonts and images and displaying them on the screen. Follow along with the code in https://github.com/EdgarReynaldo/EagleGUI/blob/0pt8pt6/examples/EagleGraphicsContextTutorial.cpp .

Window creation

Window creation is easy and only takes a few parameters. This function is contained within the system class and as such you use an EagleSystem object pointer to access it. The signature is :

   EagleGraphicsContext* EagleSystem::CreateGraphicsContext(std::string objname , int width , int height , int flags , int newx = -1 , int newy = -1);

objname is a string for the name of the window you will be creating. The object registry uses this name for reference later. width and height are the size of the window in pixels. flags comes from the EAGLE_DISPLAY_FLAGS enum and is referenced below. newx and newy are the new x and y position of the window to use. Pass -1 for both to center the window, which is the default behavior.

enum EAGLE_DISPLAY_FLAGS {
   EAGLE_WINDOWED                    = 1 << 0, ///< Make this display windowed
   EAGLE_FULLSCREEN                  = 1 << 1, ///< Make this display fullscreen
   EAGLE_OPENGL                      = 1 << 2, ///< Use OpenGL for this display
   EAGLE_DIRECT3D                    = 1 << 3, ///< Use Direct3D for this display
   EAGLE_RESIZABLE                   = 1 << 4, ///< Make this display resizable (only works in windowed mode)
   EAGLE_NOFRAME                     = 1 << 5, ///< Make this display frameless
   EAGLE_GENERATE_EXPOSE_EVENTS      = 1 << 6, ///< Generate expose events on this display
   EAGLE_OPENGL_3_0                  = 1 << 7, ///< Require OpenGL 3.0 or better
   EAGLE_OPENGL_FORWARD_COMPATIBLE   = 1 << 8, ///< Require forward OpenGL compatibility
   EAGLE_FULLSCREEN_WINDOW           = 1 << 9, ///< Make this display a full screen window
   EAGLE_MINIMIZED                   = 1 << 10,///< Start this display minimized
   EAGLE_USE_PROGRAMMABLE_PIPELINE   = 1 << 11,///< Provide your own shader pipeline for this display
   NUM_EAGLE_DISPLAY_FLAGS           = 12
};

For this example we will use an OpenGL window sized 800x600 centered on the screen by calling the following code :

EagleGraphicsContext* win = sys->CreateGraphicsContext("Main window" , 800 , 600 , EAGLE_OPENGL | EAGLE_WINDOWED , -1 , -1);

In the graphics context tutorial code we next call EAGLE_ASSERT(win && win->Valid()); to make sure the window was created successfully and is valid to draw on. After that we can do anything we want with the window. Here we will clear the screen to the default color black, flip the display, rest 3 seconds, clear the screen to white, flip the display, and rest 3 more seconds before continuing with the tutorial.

A short note on colors in Eagle ; they are quite simple. The constructors for an EagleColor are as follows :

   ///< EagleColor constructor from r,g,b or r,g,b,a values
   EagleColor(int red , int green , int blue , int alpha = 255);

   ///< EagleColor constructor from floating point r,g,b or r,g,b,a values
   EagleColor(float red , float green , float blue , float alpha = 1.0);

Each takes an rgb triplet and an optional alpha value, which defaults to full alpha, which is opaque. We will use EagleColor objects throughout Eagle.

Back to the tutorial code :

   /// Clear the window to the default color, which is black
   win->Clear();
   
   /// Update the screen by flipping the display - nothing will be shown until FlipDisplay() is called
   win->FlipDisplay();
   
   /// Wait 3 seconds so the window is visible
   sys->Rest(3.0);
   
   /// Clear the window to a specified EagleColor - in this case white
   win->Clear(EagleColor(255,255,255));
   
   /// Update the screen
   win->FlipDisplay();
   
   /// Wait 3 seconds
   sys->Rest(3.0);

Now there are 3 main capabilities of an EagleGraphicsContext. Drawing, text, and images. We will cover the functions available for each here in this tutorial except for the extensive set of drawing functions, which can all be referenced in the manual. Text and fonts will be covered first, followed by images, and then a short set of drawing functions.

Loading fonts and drawing text

Before we can draw any text, we need a font. Eagle provides both a built in and a default font, in addition to user loaded fonts. To access the built in font or the default font, simply call their getter function on a window (graphics context). The built in font is an 8x8 monochrome font for basic screen output. The default font may be adjusted by changing the default font path, size, and flags before creating the window.

EagleFont* BuiltinFont();

EagleFont* DefaultFont();

To load a font from disk, use the GetFont function shown below :

EagleFont* GetFont(std::string file , int height , int fontflags = FONT_NORMAL , IMAGE_TYPE memflag = VIDEO_IMAGE);

In the tutorial code we load a font to display the classic "Hello World" text on the screen.

EagleFont* font = win->GetFont("Data/Fonts/English.ttf" , -160);

Eagle will throw an exception in debug mode if our font was not loaded and an error message will be displayed in the log. Next we need to draw the string. The available text drawing functions are as follows :

   /**! @brief Draws the specified text horizontally left to right in color c at x,y using the specified font and alignment */
   virtual void DrawTextString(EagleFont* font , std::string str , float x , float y , EagleColor c ,
                               HALIGNMENT halign = HALIGN_LEFT ,
                               VALIGNMENT valign = VALIGN_TOP)=0;

   /**! @brief Draws the specified text vertically top to bottom in color c at x,y using the specified font and alignment */
   virtual void DrawVTextString(EagleFont* font , std::string str , float x , float y , EagleColor c ,
                               HALIGNMENT halign = HALIGN_LEFT ,
                               VALIGNMENT valign = VALIGN_TOP , int letter_spacing = -1)=0;

   /**! @brief Draws the specified multi-line text in color c at x,y using the specified font and alignment */
   void DrawMultiLineTextString(EagleFont* font , std::string str , float x , float y , EagleColor c , float line_spacing ,
                               HALIGNMENT halign = HALIGN_LEFT ,
                               VALIGNMENT valign = VALIGN_TOP);

In our code we will use the standard DrawTextString function to draw text horizontally centered on the middle of the screen in white using the font we just loaded.

   /// Clear the screen and display our hello world text
   win->Clear();
   win->DrawTextString(font , "Hello World" , 400 , 300 , EagleColor(255,255,255) , HALIGN_CENTER , VALIGN_CENTER);
   win->FlipDisplay();
   sys->Rest(3.0);

Loading images and displaying them

Loading images is very simple and can be done using our window. The draw call is simple as well.

   /// Image loading
   EagleImage* bg = win->LoadImageFromFile("Data/Images/Stallions2.jpg");
   EAGLE_ASSERT(bg && bg->Valid());
   
   /// Clear the window and draw our image
   win->Clear();
   win->Draw(bg , 0 , 0);
   win->FlipDisplay();
   sys->Rest(3.0);

The image shown is as below :

Image drawing functions are covered in the headers here :

https://github.com/EdgarReynaldo/EagleGUI/blob/0pt8pt6/include/Eagle/GraphicsContext.hpp#L460-L535

Drawing functions and screen output

Next we will cover some of the basic drawing functions.

As of Eagle 0pt8pt6 the following drawing functions are declared in EagleGraphicsContext.hpp on lines 313-458.

https://github.com/EdgarReynaldo/EagleGUI/blob/0pt8pt6/include/Eagle/GraphicsContext.hpp#L313-L458

Example code is really not necessary, as all the drawing functions are aptly named as well as the parameters and they are explained in the headers.

This concludes our basic graphics context tutorial.