Graphics in Ubuntu Linux ######################## .. include:: /header.inc .. vim:filetype=rst spell: .. _CPUfactory3: https://github.com/rblack42/CPUfactory3 To make the last few labs we will do involving our simulator project more interesting, I have set up some test code that provides a set of graphical widgets we can use to see things happen in our program. However, these are some setup tasks need to be done before you can run any of this example code. Assuming you are working in a Ubuntu VM, we will configure your machine in an interesting way. All of the code needed to make sure your VM is ready for work is available from a repo on my GitHUb_ account: .. code-block:: bash $ git clone https://github.com/rblack42/VMdev.git $ cd VMdev $ ./bootstrap.sh This bootstrap script installs a Python tool named Ansible_ with is used to provision many servers and workstations in use today. Ansible_ works very well on Linux and Mac systems, but support for running on Windows is lagging. I have used Ansible_ for years, setting up my development Mac machines freshly every semester. Ansible ******* Basically, Ansible_ uses a set of simple data files to describe what you want your machine to look like, then makes sure that setup is true on your machine. You do not need to run commands to do the setup, Ansible_ already knows how to do that. So, if you say you need a tool like ``freeglut``, which we will use for our graphics work, Ansible_ will make sure that package is installed. Ansible Control Files ===================== Ansible_ uses a markup language called YAML_ (Yet Another Markup Language) to define what you want. We start off with a simple setup that looks like this: .. literalinclude:: code/ansible/site.yml :linenos: :caption: ansible/site.yml .. note:: I keep all setup files for Ansible_ in a folder named ``ansible`` in my development system. Everything I need to configure that machine is included in that one directory, which is under Git management so I can clone it into a new machine easily! Ansible_ scripts can be set up to install the same set of tools on thousands of machines all at the same time. In fact, some data centers do exactly that to configure all of the servers they use. IN our cave we only need to set up our local machine. To do that we provide a simple ``inventory`` file that looks like this: .. literalinclude:: code/ansible/inventory :linenos: :caption: ansible/inventory I usually add a simple ``Makefile``` to make running things easier (I do not need to remember weird commands using this scheme!) .. literalinclude:: code/ansible/Makefile :linenos: :caption: ansible Makefile Ansible Tasks ============= The real magic comes in two more files we need to build that control what will happen. These files are installed in a ``tasks`` folder inside the ``ansible`` directory. Updating Ubuntu --------------- You should update the Ubuntu installer tool frequently to make sure you are running the latest versions of tools. To do that we add a ``task`` that looks like this: .. literalinclude:: code/ansible/tasks/apt-update.yml :linenos: :caption: ansible/tasks/apt-update.yml As you can see, there is nothing in here that looks like a command you need to type. Ansible_ knows how to run the appropriate command. As set up here, any time you run Ansible_ (see below) Ubuntu will be updated. Installing Our DEV tools ------------------------ Here is the important task. This one installs everything needed to build our project and handle graphics as well: .. literalinclude:: code/ansible/tasks/cpp-dev.yml :linenos: :caption: ansible/tasks/cpp-dev.yml Installing AVR tools -------------------- Since we will be doing AVR development as well, we might as well get those tools installed now: .. literalinclude:: code/ansible/tasks/avr-dev.yml :linenos: :caption: ansible/tasks/avr-dev.yml Provisioning for the Lazy Developer =================================== Now for the nice part. To get everything set up all you do is open up a command prompt window in you VM, navigate into this ``ansible`` folder and do this: .. code-block:: bash $ make Stand back, watch the messages. at the end of everything you should see a line that looks like this: .. code-block:: text PLAY RECAP ***************************************************** localhost : ok=7 changed=1 unreachable=0 failed=0 The critical part of all this is that ``failed`` number. If everything is in place with no errors, that number will be zero! You are ready to go at this point. Adding a GUI to our Simulator ***************************** .. warning:: The code described here is under active development. Some things are bound to change (hopefully for the better) as the course progresses. Most AVR projects focus on interfacing with some kind of real hardware. Obviously, we cannot hook up our simulated machine to real hardware (or could we? Hmmm!) However, we can set up a few basic simulated parts that we can "wire" up to our machine and watch things happen. .. note:: This has been a goal of mine for several semesters, and it is coming together now! To add these simulated parts, we need some graphics support. I have been using a simple graphics library for beginning C++ developers for many years. The library needs support from a package called ``GLUT``, which is getting petty old, but still works fine. We will need to add ``GLUT`` to your system. I have instructions on doing this for all platforms. In our case, the setup we added at the top of this lecture already managed to get GLUT installed in your VM. The actual version of ``GLUT`` we installed is called ``freeglut``, an open-source version of what was a closed source tool for many years. ``GLUT`` is a layer of simple routines designed to hide the real complexity of modern graphics programming. It sits on top of a high-quality graphics system called OpenGL_ which is installed on many systems, and is used in quite a few real game programs. On top of GLUT, I have added another layer, derived from code found on the Internet so long ago, I have forgotten where the ideas came from. This added layer is in the form of a single header file and a code file you simply need to add to your project. This code is not object-oriented, making it difficult to set up as a simple class we can use. Instead, it is a bunch of functions we cna call from our code as needed to generate images on the screen. Here are the files you need: * :download:`Graphics.h` * :download:`Graphics.cpp` .. note:: For convenience, everything you need ot play with these new Graphical widgets is included in my CPUfactory3_ repository. This includes testing on Travis-CI_, something we will look at in a later lecture. When we add graphics to our application, you need to consider exactly how your project should look to the user. Most graphics-based programs are never launched from the command line. The user simply double-clicks on some icon to fire up the application. Our project will support both a command line interface, and the possibility of being launched as a full graphical system. To get started, we need to look at the basic setup for our ``main.cpp`` file: .. literalinclude:: code/CPUfactory3/src/main.cpp :linenos: :caption: src/main.cpp There are a lot of ``includes`` in this file, most of which bring in some part of the new graphical system. Command Line Options ==================== I have added a few command line options to control how the application runs. They are pretty simple, just setting a few boolean variables and a counter for use when we get the machine running: .. literalinclude:: code/CPUfactory3/src/arg_parse.cpp :linenos: :caption: src/arg_parse.cpp This code adds three command line options: * -d - turn on debugging output * -g turn on the graphics system * -s - run the simulation this many steps, then stop We will add more options later, this is just a start. Graphics Setup ************** A graphics program is different from your normal application. Usually, graphics code is "event-driven", meaning the code runs in a loop looking for events to process. The underlying graphics engine takes care of updating the screen during this loop, allowing us to modify the screen to produce animation. This means that when we launch the graphics code, everything that happens will be handled by a set of functions that the engine will call as needed. Specifically, the example code sets up "handlers" for the following: * keyboard - handle keys pressed by the user * mouse - respond to mouse clicks * display - draw everything needed for one "frame" on the screen * animate - update anything needed to make the screen display something different on the next "display" call. Notice lines 23-24 in ``man.cpp``. These calculate how often we want our animation loop to run. In the example code, we are setting up the system to redraw the screen 80 times per second (The ``FRAME_RATE``. The timer function is used to make sure the machine runs at the proper speed on any platform, something needed in the gaming world! . This is fast enough that humans will see smooth animations, but slow compared to how fast we want out simulator to run. When we turn on the graphics system, we will want to run the simulator slower, so we can control it with the mouse! Each of those special functions called in ``main`` are recording the name of a function that will be called wen the indicated event occurs. These are called ``callback`` functions. This technique allows the engine to give some control to the developer so they can make things happen the way they want, without needing to hook new code deep in the graphics engine code. Callback Functions ****************** In the example code here, the callback functions are all in the following files: * src.gui.cpp * lib/graphics/keyboard.cpp * lib/graphics/mouse.cpp IO Parts Kit ************ .. _Kim-1: https://en.wikipedia.org/wiki/KIM-1 The AVR is all about interfacing with real hardware. Since this is a software simulation, we need a few simulated parts we can attach to our system so we can watch it perform. .. note:: As I was building this system, I was taken back to my first real home computer, the `Kim-1`_, bought for the then staggering price of $250 (plus a bit more for a power supply). .. image:: images/kim1-a.jpg :align: center This was my real introduction into the world of assembly language. The machine had six seven-segment displays, a hex keypad, 1K bytes of memory and an 8-bit processor running at 1 MHz. It also had a monitor program stored in 2K of ROM so you could work with the system. It could record your memory contents on an audio cassette, and then reload those bits later. It was amazing what you could do in only 1K of programmable memory. Using a simple graphics system I have had students use for many years, I was able to put together a set of parts suitable for connecting to our simulated AVR system. All we will need to do is add a bit of logic so our simulator can send signals to these gadgets. Here is a screen shot of the gadget set I put together: .. image:: images/IOparts.png :align: center In this image you see the following parts: * Simple LED lights * 7-segment LED displays * Text output control * 8x1 LED grid, assembled into an 8x8 display * Button that responds to mouse clicks. The code provided is not set up properly for our work. IT needs to be wrapped up in proper component style classes, but the code does work, and provieds a start on a usable setup for the rest of our simulator labs. Testing graphical gadgets is not easy. I "hacked" this display together in a few evenings using old-fashioned techniques. While we can test the basic functioning of something, testing what it looks like is another thing entirely. It is possible, just way beyond what we can do in this course. Running the Demo ================ Assuming you have cloned the CPUfactory3_ repository, all you need to do to try it out (after installing the needed library) is do this: .. code-block:: bash $ cd cosc2325/CPUfactory3 $ make $ ./CPUfactory3 -g The make file has a ``run`` task that will run the application, but not in graphics mode. Press the "q" key to halt this graphics display. Click the mouse anywhere in the screen to get the current mouse coordinates. The HEX display will switch from counting up to counting down if you click the mouse anywhere on the screen as well. Clocking on the small "On" button will toggle it from red to green. All of the code provided is fresh from a serious "blasting" session. I managed to gt several things running, and am leaving that code in a fairly ugly state. Your team should clean up some of this code to make it come up to our standards. All provided code does pass the ``cpplint`` test at [resent. .. warning:: Running ``make test`` will fail, because some of the files needed are to be provided by you. I have left test code here to exercise parts we havenot built yet. You are free to use these for your own testing. The ``modular-make`` setup here has been tested on all three major platforms, and works as expected. The actual development version of this project is being tested on Travis-CI_, something we will set up in a later lecture.