To get going, you need to clone the repository we have set up for you on Gitlab that has been pre-populated with starter code. We will be using Git for source control. For more detailed information, refer to the git tutorial. In order to get the source code, follow the directions below:

1. Log on to Gitlab, and if you haven't already done so, add an ssh key
2. Open 'Git Bash' on Windows (Search for it in the start menu if you are having trouble finding it)
3. Navigate to the parent directory of where you would like your repository to live. We recommend putting it somewhere in your Z: drive
4. Run the following command to make a local copy of your repository named 'impressionist'. You can find your repository on GitLab under the projects tab on the right side of your dashboard.

   $ git clone git@gitlab.cs.washington.edu:cse457-15au-impressionist/YOUR_REPO.git impressionist

5. Open the project in Visual Studio. Build and run it. You should see a graphical interface with a lot of missing functionality. It will be your job to implement these features.
6. After you've made some changes to the skeleton (perhaps you added a triangle brush), commit your files and push them so they are accessible to you.

   $ git add --all

   $ git commit -m "added a triangle brush"

   $ git push origin master

7. If you have made changes remotely, run

   $ git pull

   to update your copy of the repository with their changes before you start working to avoid merge conflicts.

Code Turn-in:

You need to submit your binary and source code by the due date to the Catalyst Dropbox. Please submit a readme that describes any bells, whistles, and anything out of the ordinary you did for the project. This will help us out when we are grading your project. If you did your development under Linux, please note that as well.

Your turnin should be a zip file containing two folders that looks like this:

binary/	[program].exe - Executable file compiled in release mode Files needed by the executable - this includes textures, images, shaders, and other files README.txt - only if you did anything out of ordinary
source/	Everything needed to compile and run your project Please do not include the "debug/" and "release/" folders

The grading will consist of a staff member running your project right out of the binary directory and stepping through the features. We will verify the timestamp of the executable and consult source code as needed.

Artifact Turn-in:

When you are done with a project, you will create a project "artifact" to show off the features of your program.

This is required. You will lose points if you do not submit at least something. We will not grade on artistic merit. However, after everyone submits their artifacts, we will create a gallery on the course website where you will vote on your favorite artifacts! The winner and runners-up will receive a small amount of extra credit. So be sure to try your best!

The main instructional lab for our course is CSE 022, in the basement of the Allen Center. As a registered student in the class, you should have access to this lab. Contact cardkey@cs if you are not able to enter the lab with your cardkey.

The computers are Windows 10 workstations. Applications are built using Visual C++, the FLTK UI toolkit, and OpenGL.

Rules for CSE 022:

• The machines in CSE 022 are primarily for the use of cse457, cse455, and cse557 students working on assignments for those courses. If you are not a graphics student, or not working on the course, you may use the machines in CSE 022, but must give up your machine if someone needs it for the course.

• If for some reason, you get hung, mail support@cs. They will take care of this for you.

• The lab has copies of course reference material, including textbooks OpenGL reference texts. These may not leave the lab, and please return them to the bookshelf when you are done using them.

In addition to the above rules, the Lab Community Committee has created a set of guidelines about general lab use. The main points are:

• Be aware of yourself and your space. Remember that your behaviour affects others.

• The labs are an academic community of which you and your fellow students are citizens.

• We are each responsible for our community's working environment.

• Follow the Golden Rule: Treat others as you would like to be treated.

Please read the complete Lab Usage Guidelines.

1. Make sure you have FLTK 1.3.3 installed on your computer. If you're running Windows and using Microsoft Visual Studio 2015, then you can download and run the FLTK Installer. Otherwise, you'll need to download and compile the FLTK source code.

2. Download git on your machine.

3. Follow the Getting Started steps above.

4. You may need to point Visual Studio to the correct include and library directories for the FLTK that came in your repository (since normally it points to the local one on each lab machine).

5. Open the .vcxproj file to load the project into Visual Studio.

Visual Studio 2015

Visual Studio is the Microsoft IDE for windows based development. We will use Visual Studio 2015 in the labs. You can find the community edition for free here.

Do you have the windows SDK too? If the Visual Studio install did not install the SDK, then you might run into errors of the sort gl.h ot glut.h not found. Installing the Windows SDK will help.

Fastlight Toolkit (FLTK)

FLTK is a C++ graphical user interface tookit for X(Unix), OpenGL and Microsoft Windows(Nt 4.0, 95, 98).

We won't cover much about FLTK in here, since we will be using FLUID to generate the FLTK source code. But it is good to learn the basic of FLTK so that you can be more familiar with Fluid later on. For this, refer to the to see the complete FLTK Programming Manual.

Installation on Windows

1. Install FLTK files

• Download the fltk-1.3.3 installer.
• Run the installer. It will install FLTK in C:\Program Files\fltk-1.3.3.
• Compile your project. If you don't get errors about the file "FL/fl.h" not existing, etc., then you're done! The skeleton code expects the FLTK files to be where the installer puts them, so if you have problems, you should probably contact the CSE 457 staff.

2. Configure Visual Studio (MSVC)

• Open MSVC, and click Tools->Options.
• In the left pane, expland "Projects and Solutions"
• Choose "VC++ Directories"
• In the right pane, change the drop-down to "Include Files"
• Add the item "C:\Program Files\fltk-1.3.3"
• Add the item "C:\Program Files\fltk-1.3.3\png"
• Add the item "C:\Program Files\fltk-1.3.3\jpeg"
• Add the item "C:\Program Files\fltk-1.3.3\zlib"
• Change the drop-down to "Library Files"
• Add the item "C:\Program Files\fltk-1.3.3\lib"

3. Verify that your project is linking with the correct library

• In MSVC, click Project->Settings...
• Click the "C++" tab.
• Change the "Category" drop-down to "Code Generation".
• If the project configuration is Release, change the "Use run-time library" drop down to "Multithreaded DLL".
• If the project configuration is Debug, change the "Use run-time library" drop down to "Debug Multithreaded DLL".
• Click the "Link" tab.
• If the project configuration is Release, make sure that "fltk.lib" (and not "fltkd.lib") is present in edit box labeled "Object/Library modules".
• If the project configuration is Debug, make sure that "fltkd.lib" (and not "fltk.lib") is present in edit box labeled "Object/Library modules".

Installation on Linux

1. Install Mesa

As the first step, you must install MesaGL. To install it:

> gunzip MesaLib-3_0_tar.gz
> tar -xvf MesaLib-3_0_tar
> cd Mesa-3.0
> make linux-386
.....

Several minutes later, you will have libMesaGL.a and LibMesaGLU.a in Mesa-3.0/lib and a directory called GL in Mesa-3.0/include. I usually prefer to copy all these files into ~/local/lib and ~/local/include such that I can access all the libraries without remembering tons of paths.

2. Install Fltk

Now, we try to make fltk. You can get the source from here.

> gunzip fltk-1.3.3-source.tar.gz
> tar -xvf fltk-1.3.3-source.tar
> ./configure 
> make

Create a local directory in you home dir
Open makeinclude file and change the prefix variable to the your local
directory

> make install
> cp fltk-1.3.3/fluid/fluid ~/local/bin
> cp fltk-1.3.3/

You will have 'fluid' in ~/local/bin, 
two directories, FL and Fl, in include 
and libfltk.a in lib.

Now everyting is in ~/local, you need to change the value of the variable, $(LOCAL), in Makefile to ~/local.

Git is a modern version control system for managing the sharing and versioning of your source code. Git is a "distributed" version control system, as opposed to classical systems such as CVS and Subversion which are based on a single central repository. While distributed version control is very powerful, this tutorial will teach you to use git in a "client-server" fashion that mimics the classical version control systems that you may already be used to.

Cloning the Repository

Log on to Gitlab, add an ssh key, and then find your group's repository under the Projects tab.

Click your repository's name, and at the top of the page there should be a string you can copy of the form git@gitlab.cs.washington.edu:cse457-15sp/YOUR_REPO.git, where YOUR_REPO is your group identifier.

Copy that string, and in a shell (such as Git Bash or Git Shell), run:

$ git clone copied_string

This will create a directory named YOUR_REPO in the current directory

We recommend renaming the local copy of the repository to something more descriptive, by running:

$ git clone copied_string descriptive_name

This will create a directory named descriptive_name in the current directory

If you are prompted to enter your password that means you haven't set up your ssh keys in gitlab properly. Do that now to avoid repeated password prompts as you push and pull things from gitlab.

Committing other changes to the repository

The commit and update process in git differs slightly from that of other version control systems that you may have used. To illustrate how it works, we'll make a minor change to one file and create a new file.

Copy the contents of pointBrush.h and paste into a new file called lineBrush.h. Replace all occurrences of 'point' with 'line'. In impressionistDoc.cpp, add lineBrush.h to the brush includes. (search for pointBrush.h if you're having trouble finding this)

Now run the git status command and observe its output:

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

    modified:   impressionistDoc.cpp

Untracked files:
(use "git add <file>..." to include in what will be committed)

    lineBrush.h

no changes added to commit (use "git add" and/or "git commit -a")

This output shows two things: first, you must explicitly add new ("untracked") files to the repository before they can be committed (as is true in other version control systems), and second, you must explicitly stage your changes before they will be committed (unlike subversion, which will automatically commit all of your changes if you just run svn commit). To further illustrate this, run the git commit command:

$ git commit -m "Adding the line brush header file."

This command will be a no-op: you should see the same output as from the git status command, ending in the same message: 'no changes added to commit (use "git add" and/or "git commit -a")'. To add your changes to the commit set, you must use the git add command on the changed files (whether they are new files or files already in the repository!):

$ git add impressionistDoc.cpp
$ git add lineBrush.h
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD ..." to unstage)

    modified:   impressionistDoc.cpp
    new file:   lineBrush.h

You can see that the change to the impressionistDoc.cpp file and the addition of lineBrush.h have now been staged for the commit. To commit all of the changes that you have staged, run git commit:

$ git commit -m "Adding the line brush header file."
[master 41a5c0d] Adding the line brush header file.
2 files changed, 2 insertions(+), 0 deletions(-)
create mode 100644 lineBrush.h

However, at this point you have committed some changes, but your commit is not yet visible to the other users of the repository. git separates the notion of committing changes from the notion of "pushing" your update to the central repository. This can be useful for an individual developer that wants to make many changes to the code in many small logical commits before pushing all of them to the central repository, but for your CSE 457 projects you will probably just want to push after every commit.

To push your commits to the central repository, simply run git push:

$ git push
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (4/4), 312 bytes | 0 bytes/s, done.
Total 4 (delta 0), reused 0 (delta 0)
To git@gitlab.cs.washington.edu:cse457-15sp-impressionist/YOUR_REPO.git
eb27358..c3615e1  master -> master

Notes:

• If your push fails, it may be because you need to run a git pull to update your repository first (and potentially resolve conflicts) before pushing your new commit. See Updating your local repository below.

• If you get a warning that push.default is not set, you can make that message go away by setting it to simple using the git config command given in the warning message.

• If you ever run the git status command and see the output "Your branch is ahead of 'origin/master' by N commits", then this means that you have local commits that have not been pushed to the repository yet.

• Remember to push your commits! If you are not used to using git, then this may be the hardest thing to get used to. Try not to forget to do this, or your group members will wonder why it seems like you're not doing any work.

Updating your local repository

To update your local copy of the repository with commits that other members of your group have made, simply use the git pull command. It will either show:

$ git pull

Already up-to-date.

or something like:

$ git pull
...
impressionistDoc.cpp                |    1 +
lineBrush.h                     |    1 +
2 files changed, 2 insertions(+), 0 deletions(-)
create mode 100644 lineBrush.h

As with any version control system, pulling updates from the central repository may cause conflicts with changes that you have committed locally. Pay attention to the output from your pull command for instructions to resolve conflicts; generally, resolving a conflict entails opening up the conflicted file(s) in your editor, finding the conflicts (surrounded by the text markers <<<<<<<, =======, and >>>>>>>), fixing the conflicting code, staging the changes (git add) and committing and pushing again. For more information about resolving conflicts, the github user manual has a useful webpage.

Git GUI Clients

Since it may be hard to visualize what is going on with Git repositories in just the terminal, there are some very high quality GUI clients available built on-top of the command-line Git. SourceTree lets you perform all the common commands with buttons and provides important visualizations of the branches and commit history. Going back to a previous commit is as simple as clicking on it and hitting checkout. GitHub Client is another one.

• C++ Language Tutorial - useful for quick reference

• Standard Template Library (STL)

• ACM C++ Tutorial

• Thinking in C++ and Thinking in Cby Bruce Eckel

• CSE303 Spring 2009

  1. Introduction to C++
  2. Classes and Objects in C++
  3. Advanced Classes and Objects in C++
  4. Inheritance in C++
  5. Inheritance in C++ continued

• CSE303 Winter 2010

  1. Introduction to C++
  2. Manipulating objects and inheritance
  3. Inheritance (virtual functions and abstract classes)
  4. C++ Templates and STL
  5. C++ const type (second half of lecture)

OpenGL is a 2D/3D graphics library. It is based on IRIS GL, developed at Silicon Graphics for their high-end workstations. You can find more information about the OpenGL standard at www.opengl.org. This document is not a tutorial, but introduces some of the basic concepts of OpenGL that will be used in our projects, and provides pointers into the documentation.

• The best book for learning OpenGL is the OpenGL Programming Guide, "The Red Book."

• The Official OpenGL Documentation is great refrence material.

• For tutorials on OpenGL, check out this link.

OpenGL Conventions

All the functions in the OpenGL library have names beginning with "gl". Defined constants have names beginning with "GL_".

It common for there to be a family of functions for performing the same operation, differing only in the number and/or types of arguments accepted by each. The names of these functions have tags at the end to indicate the type of argument. The whole family will be referred to with a star syntax. For instance, glColor*() refers to any of the 32 functions available within OpenGL for setting the current color, including:

glColor3f( GLfloat, GLfloat, GLfloat )

glColor4d( GLdouble, GLdouble, GLdouble, GLdouble )

glColor3ubv( GLubyte* )

There is also a library of utility functions whose names all begin with "glu". These are simply convenience functions for doing some common tasks that take a few OpenGL commands to perform.

OpenGL as a State Machine

OpenGL keeps a large amount of state. It has many modes which can be switched on and off with the glEnable and glDisable commands. You should think of each function call as manipulating this state, rather than performing a specific drawing operation. To enable high performance, implementations of OpenGL are allowed to buffer commands almost arbitrarily. When you have sent some commands to OpenGL and want to be sure that the results actually appear on screen, call glFlush to force OpenGL to complete.

The OpenGL state is kept in a data structure called a rendering context. We will typically create one rendering context for each OpenGL window. This keeps state changes for drawing in one window from interfering with drawing in the other windows. Switching to another context is done by calling wglCurrentContex.

Drawing Primitives

Drawing in OpenGL consists of calling glBegin to tell OpenGL what you want to draw, then a series of calls to glVertex* to specify the geometry, then a call the glEnd to finish up. The single argument to glBegin tells it how to interpret the series of vertices you are going to throw at it. Here are some of the valid things to send to glBegin:

GL_POINTS	draws each vertex as a point
GL_LINES	draws a segment connecting the vertices 1 and 2, a segment connecting vertices 3 and 4, 5 and 6, and so on
GL_TRIANGLES	draws the first three vertices as a triangle, the second group of three as another triangle, and so on
GL_POLYGON	takes the vertices as a single, simple, convex polygon

There are several other options, see the manual for more explanation. Note that whenever you tell OpenGL to draw a polygon, it must be flat and convex. Triangles are easy, because they are always flat and convex, but with higher-order polygons you must be careful or your results will look wrong. Each polygon has a front side and a back side, which can be rendered differently if you choose. The front side is defined (by default) as the side from which the vertices appear in counterclockwise order.

The vertices you specify are coordinates in 3D space. They are transformed by the current modelview matrix, then by the current projection matrix to determine where they map to on the screen.

Matrix Stacks

For a more detailed and helpful explanation, visit here.

Contained in the OpenGL state are two matrices which affect how geometry appears on the screen. The projection matrix determines the position and orientation of the camera. The modelview matrix is used to transform geometry before rendering it. In our projects, the projection matrix will typically be set up by the skeleton code. You will change the modelview matrix to affect how primitives are drawn on the screen.

The state maintains a stack for each matrix, with the top matrix being the one that is in force. You can thus make temporary changes by pushing a copy, altering the matrix, using it, then throwing it away with a pop. Since a full stack is maintained, you can nest these temporary changes to (almost) arbitrary depth. The useful commands for manipulating these stacks are:

glMatrixMode	Selects which matrix stack is being manipulated, GL_PROJECTION or GL_MODELVIEW. (Actually, there is a third one for controlling texture mapping, but you can read about that in the manual.) The remaining commands all affect the currently selected matrix stack.
glLoadIdentity	Replaces the top element of the stack with an identity matrix.
glPushMatrix	Duplicates the top element of the matrix stack.
glPopMatrix	Pops and discards the top element of the stack.
glTranslate* glRotate* glScale*	Composes the top element of the stack with a transformation.

Manipulating the Frame Buffer

Frequently you will want to copy around blocks of pixels, rather than drawing individual primitives like lines and polygons. You could do this by drawing individual GL_POINT objects, but that would be horrendously slow and inefficient. Instead, there is a set of OpenGL functions for copying blocks of pixels to and from the framebuffer.

glReadPixels, glDrawPixels	read/write a block of pixels from/to the frame buffer
glReadBuffer, glDrawBuffer	select which buffer is read/written
glPixelStore*	specify how pixels read/written are arranged
glRasterPos*	set the starting point for pixel write operations

Keep in mind that we will frequently be using a double-buffered framebuffer to provide smooth animation. With double-buffering, objects are typically drawn into the "back" buffer, which is then swapped with the front buffer (with the SwapBuffers function) to provide the illusion of instantaneous redrawing. It is important to understand which buffer you are reading or writing when doing block pixel operations.

*a step by step guide to creating your final media file*

1. Export your animation (will create a sequence of consecutively numbered frames)

   • If your artifact uses your particle system, remember to toggle 'Simulate' before you generate your rendered frames.
   • Make sure the FPS slider is set to 30 frames per second.
   • File->Save Movie As...
   • Provide a name that will be the prefix for the file names of each of the frames you generate.
   • 'Ok'

2. From here on out we'll be using Adobe Premiere (Pro 4.0). The help site may be useful.

3. Create a new project in Premiere. Select the "Custom Settings" tab (as opposed to the "Load Preset" tab). Select "General" from the list on the left and give your project a name. There are a few things you want to be sure of:

   • General->General->Editing Mode: should be Desktop.
   • General->General->Timebase: should be 29.97 frames/second (since that's what you exported earlier). If you exported at some FPS other than 30, make the appropriate adjustment.
   • General->Video->Frame Size should keep same aspect ratio as generated frames (e.g. 680x592, 640x480, etc.)
   • General->Video->Fields: No Fields (Progressive Scan), because your input has no fields.
   • General->Audio->Sample Rate: should match your soundtrack (probably 44100 Hz)

4. Import your sequence

   • File->Import...
   • Select the first frame in the sequence and check 'Numbered Stills' (in the lower area of the dialog box)
   • 'Open'
     • the sequence will appear in the Project container
     • if the import was done correctly, the icon for the sequence should look like a filmstrip.
   • Drag the sequence into one of the video channels in the Timeline window.
   • Make sure its left edge is precisely at 00:00
   • Adjust the work area slider (at the top of the Timeline window) so that its length equals that of the animation you just dragged there.

5. Import any audio.

   • File->Import...
   • Select the audio clip you want to import.
   • 'Open'
   • Drag the imported audio clip to an audio channel.

6. Make any adjustments necessary.

   • multiple sequences can be added to either video channel.
   • To cut a sequence into two pieces (for compositing, or time editing),
     • find the Razor Tool in the toolbox in the left part of the Timeline
     • cut the sequence/file at the desired time position
   • To change the length of a sequence
     • find the Rate Stretch Tool (Click and hold the Rolling Edit Tool to access it)
     • drag either end of your sequence to change the length
   • To edit audio, we highly recommend the free tool Audacity. Premiere can also do some simple audio editing, such as fade-ins/fade-outs.
   • Preview
   • If satisfied with the preview, export.
     • File->Export->Adobe Media Encoder...
     • Click on the Output tab.
     • In the Export Settings section set Format to H.264.
     • Also in the Export Setting section, set Preset to HDTV 720p 23.976 High Quality. After setting this preset, make a couple of adjustments: edit the Frame Rate to 29.97 and bring the bitrate down a bit (you can play with it, but Target: 3Mbps and Maximum: 5Mbps ought to be more than enough).
     • Make sure that the other export settings are set to the correct frame size (we will be projecting it on a 1024x768 projector so keep your resolution within reason) and Field Order, which should be set to None (Progressive). Double-check that you've made these settings appropriately.
     • Click Ok.
     • Specify movie name and save location. If your animation has audio, please have the suffix "_with_audio.mp4" in the file name so we can test to be sure the audio is working, for example the save file might be "fancy_movie_with_audio.mp4".
     • Ok
   • Make sure you check your artifact before submitting it! It should work (audio and video) decently in Windows Media Player and Quicktime.