..  _cpp-graphics:

############
C++ Graphics
############

..  include:: /references.inc

Once you completed the graphics setup instructions, you now have two graphics
libraries on your system: OpenGL_ and Glut_. Both of these have a huge number
of folks working to build some pretty cool graphics applications. We are not
ready to do that, but we can tap into their work and do some fun stuff. The
problem is that even with the new addition we installed, all of this is still
too complicated.

**********************
Adding the class files
**********************

I have created a simple pair of files we can add to our projects to build
simple graphics applications.  Most significant programs involve more than one
file, so this is not at all unusual.

The two files we will need are:
      
    * ``Graphics.cpp`` - new graphics functions we can use 
    * ``Graphics.h`` - Needed to tie your program to the graphics routines
    
We will add the first file to our program project, then ``include`` the second
file in our graphics programs. CLion_ will take care of hooking everything
together.

Don't panic
===========

If this scares you, don't panic!  Many other students have managed to get this
working.  Most of them enjoyed the projects we did in this part of the class.

*****************
Setting up a demo
*****************

To get all this working do this:

    * Open up CLion_

    * Choose ``File --> New Project``

        * Change the "Location" to build a ``GraphicsDemo`` folder
      
        * Click on the ``Create`` button at the lower right          

Now, we need to check things:

    * Edit the ``main.cpp`` file for it says "Graphics Demo" instead of "Hello
      World"

    * Run this code to make sure everything is set up correctly
    
    * Save your project as usual

This program needs a bit more setup than our earlier work. You will be adding
two more files to your project. If you are getting overwhelmed by all this,
please be patient. I will give you plenty of time and help to get things going.
Just follow the notes and know that many classes before you have gotten through
this, and had fun with the result!

Hello, Graphics World
=====================

Modify your ``main.cpp`` file so it looks like this:

..  code-block:: c

    #ifdef __APPLE__
    #include <GLUT/glut.h>
    #else
    #include <GL/glut.h>
    #endif

    #include "Graphics.h"

    void drawScene(void) {
        // your code goes here
    }

    int main(int argc, char ** argv) {
         graphicsSetup(argc, argv);
         glutDisplayFunc(drawScene);
         glutMainLoop();
    }


That stuff looks pretty scary! The first few lines will make this program work
on either a Mac of a Windows PC. (That sure looks like a strange IF-THEN-ELSE,
and it is, but those lines are aimed at the compiler!) You probably are using a
PC, but others, including me, are using Mac systems. This is a common issue in
programming since the two systems set things up differently.


Make sure you type everything you see exactly as shown. The names and function
calls you see for things like ``glutDisplayFunc`` are parts of the ``Glut``
library, and they set up the program to draw the things we see in our
``drawScene`` procedure. It may seem strange to put the name of one procedure
into the call to another procedure as a parameter, but it is legal, and is
required by ``glut`` to make it draw images on the screen.  For now, just
consider it magic!

Wait, we are not done
=====================

The code just shown is incomplete.
See the "your code goes here" line?
We will put our own code here.
Make sure you do not mess anything else up!
We also need to add out additional files.

Adding the Graphics files
-------------------------

Copy the needed files from the folder you set up when you worked through the
:ref:`clion-graphics-setup` notes. 


    * ``Graphics.cpp``
    * ``Graphics.h``
    * ``CMakeLists,txt``

Once this is finished, you should have three files in your project


Graphics Procedures
===================

Now, we can now draw simple shapes
    
    * Boxes
    * Circles
    * Triangles

We can also control the colors used

Graphics window
---------------

All drawing is done in a 500x500 pixel window.  A ``pixel`` is one dot on your
screen.  There is a ``coordinate system`` associated with this window.

    * ``X`` runs from 0 to 500 from left to right.
    * ``Y`` runs from 0 to 500 from bottom to top

    * (The ``origin`` is in the lower left corner)
      
The simple graphics procedures I have provided give you the ability to draw a
few simple objects on the screen and control where they are and what size and
color they are. The code creates a square window on your screen 500 pixels wide
and 500 pixels high. (A pixel is one dot on your screen, which is probably
running with 1024 pixels horizontally, and 768 vertically (or more if you have
a newer system). In the procedures I have created, the origin of the system is
at the lower left corner of the window.  **x** coordinates go from 0 at the
left to 500 at the right, and **y** goes from 0 at the bottom, to 500 at the
top. You will need to figure out what coordinates (**x,y**) you need to work
with when you use the simplified graphics procedures.  Here are the routines
you can use for starters:

Drawing boxes
-------------

To get started, here are a couple of new functions:

    * drawBox(x1,y1,x2,y2)
    * drawFilledBox(x1,y1,x2,y2)

Here **x1,y1** and **x2,y2** define the box. These points are the opposite
corners of the box.  These functions do not return a value. You ``call`` them
by putting them on a line by themselves.  Make sure you end the line with a
semicolon!

Remember that when you use these functions in your program, they are a
statement all by themselves and will need a semicolon after them like all
statements in ``C++`` do.

How about a circle
------------------

This function draws a circle;

    * drawCircle(x,y,radius)

Here **x,y** is the coordinate of the center of the circle.  **radius** is
(well, you know!)

Ready for triangles?
--------------------

These functions draw triangles:

    * drawTriangle(x1,y1,x2,y2,x3,y3)
    * drawFilledTriangle(x1,y1,x2,y2,x3,y3)

Here, **x1,y1**, **x2,y2**, and  **x3,y3** set the three corners.

Simple lines
------------

We can draw a straight line using this function:

    * drawLine(x1,y1,x2,y2)

The line goes from **x1,y1** to **x2,y2**.

Setting colors
--------------

Each graphic object is drawn with a colored pen. 
You select the color for the pen using this function:

    * setColor(color)
    * where ``color`` can be one of these names:
        * WHITE, BLACK, RED, BLUE, GREEN, GREY, PURPLE, FOREST_GREEN
        * MIDNIGHT_BLUE, CYAN, MAGENTA, YELLOW, BROWN
        * (case is important here)

You must type in the name in all caps, exactly as shown above. Lower case
names, or misspellings will cause errors when you try to compile your code.

*************
A simple demo
*************

Here is the code we need to add to test our routines

..  code-block:: c

    void drawScene(void) {
         clearWindow();
         setColor(YELLOW);
         drawFilledTriangle(200,125,100,375,200,375);
         glEnd();
         glutSwapBuffers();
    }


Let's add a few more objects to our drawing Add these lines (inside the
``drawScene`` function:

..  code-block:: c

    setColor(BLACK);
    drawLine(200,200,400,400);
    setColor(RED);
    drawFilledCircle(100,100,100);
    setColor(MAGENTA);
    drawFilledBox(300,300,400,400);

Final demo output
=================

..  image:: images/glut-demo.png
    :align: center

If you have any problems getting this running, send me an email and I will help
you through your problems. Once things are working, try the next lab
assignment. It is not too hard!

******************
The Graphics Files
******************

Just to make sure you have the current versions of these files (there are
several older ones around), here are the files I am using for this
class. You do not need to understand what is in these files. They are
provided so you can check the files you download, if you run into
problems:

:Graphics.h:

..  literalinclude::    code/Graphics.h
    :linenos:

:Graphics.cpp:

..  literalinclude::    code/Graphics.cpp
    :linenos:

..  vim:set filetype=rst spell: