Session 1 - Setting up the project and GitHub

Welcome to this 217CR tutorial series!

By following these sessions, we will create the underlying areas needed for a physics engine. As always, if you have any questions (or spot any typos), feel free to talk to course staff or email me at ab8809@coventry.ac.uk.

For this week's session, we will be setting up GitHub and starting the base C++ project. This will get us ready for the later weeks and become a start for your coursework.

Setting up in GitHub

As you will know by reading the assessment brief, your coursework has to be on the Coventry GitHub server and be in a certain organization. (If it is not, it may receive a 0 mark!)

Go onto the Coventry GitHub server via https://github.coventry.ac.uk and sign in via the top right. This will be your normal username and password you use to log into university PCs.

If you cannot sign into the server, talk to me / email me ASAP as this needs to be sorted out.

Once you have logged into the server, go to the 217CR organization in 1 of 3 ways.

If you cannot access the organization, I have to manually add you to sort it. Talk to me ASAP.

On the main screen, clicking the dropdown list on the left side and selecting 217CR-1920JANMAY and then "View organization".
On the main screen, clicking your profile picture in the top right, then "Your Profile", then selecting 217CR-1920JANMAY via the icon on the left side.
Using the direct link - https://github.coventry.ac.uk/217CR-1920JANMAY

Once there, create a new repository via the green "New button".

For the repository name, call it something obvious (and add your student ID) to the front.
Set it to private (or everyone in the university can see it!).
Initialize a README file.

By doing all of this, it means that the markers will be able to see it, that other students cannot and that you can clone it straight away to your PC.

Finally, add the module staff to your repository so they have access to it. (Our information can be found on the 217CR moodle page under Module Essentials.)

Go into your repository from the website, click "Settings", then "Collaborators", and then search for, and add, both members of module staff (Ian and Will) to the page.

Cloning the repository

Once you have made your repository, it should take you to it's page. (If you have backed out of this, you can always find it by clicking on your profile picture and selecting "Your repositories".)

The next step is to clone this repository to your PC so you have a local copy to do changes on.

For these tutorials, I will be using the command line (cmd) to use Git. You are allowed to use programs like GitHub Desktop (which can be accessed via AppsAnywhere) but if you come into problems with them, staff might not be able to help.

To clone a respository you will need the URL of it. Copy this from the address bar of your browser or use the green "Clone or download" button and copy the URL from the pop up box.

Open command line by typing cmd into Windows search.

Once there, you might have to navigate to your user area on the hard drive.

The following cmd commands will be helpful to do this.

Command	Explanation
C:	Will change what hard drive disk is currently looked at.
cd "folder name"	Go into that directory / folder.
cd ..	Go back a directory / folder.
dir	Print out what is in the directory.
mkdir "name for directory"	Create that directory / folder.
git clone "url"	Clones the repository into the current directory you are at.

These are the steps I took to get to my Documents folder for example.

Make sure you are at a sensible place directory wise before you clone your repository so you can find it later!

Once at a good directory, git clone your repository. It might ask you to log in with your GitHub credentials.

When you have submitted them, the repository (and it's files) should now be on your PC.

At the moment, it should only be the README file.

It is here that we will create a C++ project so it is in the GitHub repository, meaning we can push and pull changes to it.

Creating a C++ Project using Visual Studio

If you are not using Visual Studio 2019

Open Visual Studio and Click "File" -> "New" -> "Project.."
Select "Empty Project".
Make sure "Create directory for solution" is unticked.
Give it a sensible name.
Make sure the location is the same as where the README file is stored.

If you are using Visual Studio 2019, click "Continue without code".

Click "File" -> "New" -> "Project.."
Pick "C++" as the Language to filter the list.
Select "Empty Project" and then "Next".
Give it a sensible name.
Make sure "Place solution and project in the same directory" is ticked.
Make sure the location is the same as where the README file is stored.

Once this has been done, click "Create".

We need to create the .cpp file that will hold the main() function. Remember, every C++ program needs a main() function to run.

This can be done by right clicking "Source Files" on the right hand side (in the Solution Explorer) and clicking "Add" -> "New Item...".

Make sure C++ File (.cpp) is highlighted and either change the name (I always use main.cpp) or keep it as Source.cpp and click "Add" in the bottom right.

Type in the following code to get us started and make sure it all works. Once you have typed it in, click "Local Windows Debugger" (or hit "F5") at the top middle of the screen to compile and run the code.

#include <iostream>

int main(int argc, char** argv)
{
	std::cout << "Hello world!" << std::endl;
	return 0;
}

That should pop up a console window with "Hello world!" in it.

Using OpenGL with the project

The following section is aimed at Windows machines. If you use a Mac or Linux, this will be different for you.

Now the project is created, we will need to display something to the screen to see the physics in motion.

For this, I will use a legacy version of OpenGL which will most likely differ from what you are taught in 212CR. The graphics implemented as part of this tutorial series are not enough to pass in the 212CR module.

The libraries we will be using are:

GLEW
FreeGLUT
GLM

These are the same versions as the ones from 212CR so they should not cause any issues overall.

You can download the library files I use through-out this tutorial series by downloading and extracting the "Library Files" .zip file on the module Moodle page.

These libraries are created for a certain build of project which can be a mix of Debug or Release and Win32 (x86) or Win64 (x64). For our case, these are for both Debug or Release and Win64 (x64).

We can change these in Visual Studio via the two dropdowns next to "Local Windows Debugger". Make sure your project shows "Debug" and "x64".

We now need to place these library files in a place where Visual Studio (and your code) can see and use them. Download (and extract) the files with the link above now if you have not already.

Files you should have after extraction
include folder
freeglut.dll
freeglut.lib
glew32.dll
glew32.lib

This is a 2-step process involving:

Moving all the library files somewhere helpful
Telling Visual Studio where these files are

For moving the library files, we shall place them where the project files are. This makes sure that the project always has the files (and a computer change / USB stick removal does not remove them!).

Don't know where your project files are? Right click the project name in "Solution Explorer" and select "Open Folder in File Explorer".

Your project files should now look something like this. (Of course, your project name will be different to mine!)

Moving the files is not enough. We now need to tell Visual Studio where these files are by 'linking' them.

We can do this via the "Property Page" of the project. You can access this in 1 of 3 ways:

Click "Project" at the top left of the screen, then "Properties".
Right click the project name in the "Solution Explorer" and select "Properties".
Click the "Solution Explorer" so you have selected it and hit "Alt + Enter" at the same time.

When the "Property Page" window has opened, make sure it says "Active(Debug)" and "Active(x64)". (If it does not show that, close the window, change it in the 2 dropdowns in Visual Studio and come back to the "Property Page" window.)

Select "C/C++" and type include into the "Additional Include Directories" textbox.
Select "Linker" and type include into the "Additional Library Directories" textbox.

Base Code

This week, we will just add some base OpenGL code. This is a static scene (so nothing moves) and is just to make sure everyone has got a working Visual Studio project that can run OpenGL content ready for later weeks.

Copy all the code from the "BaseCode.cpp" which is on the Week 1 GitHub page and paste it over everything in your "main.cpp" or "Source.cpp".

Run the code to get the following scene.

If you do not get the following scene, something is wrong. Look over the above tutorial again and see if you missed anything. The error messages shown in Visual Studio should give you a loose guide. If you get stuck, ask for help from the module staff.

Pushing the changes to the repository

We return to using Git now to save our progress on the project. Once you have everything working without errors, we will push our changes to the project (and to the repository) to the GitHub server.

We do this via 3 commands (which you should be used to from ALL!):

Git commands
git add .
git commit -m "some kind of message"
git push

Go into command line and navigate to where your repository is saved. (Make sure you are in the folder that contains the README and your project files! You can check with a dir command like in my example below.

Once there, use the three above commands to push your changes to GitHub. You can check the website version to make sure the push has happened.

Did something stop you using git add .? Either way, read the next section about .gitignore!

The power of the .gitignore file

Some of you might of got the above error when you tried to use git add.. This is because your project (and Visual Studio) was still open at the time of the add command and both Visual Studio and Git were trying to access a project file at the same time.

The way to solve this is to close Visual Studio fully and then use the 3 commands to push the changes to the repository. Of course, this gets annoying fast if you have to close and re-open Visual studio every time you want to push something!

This is where a .gitignore file comes in handy... This file means that whatever file extensions / folders are written in it are not considered when pushing and pulling from the repository.

This allows us to remove the files that would be open when Visual Studio is, meaning we:

Can push without the above error
Stop unneeded files from being pulled/pushed saving on download time!

Download the .gitignore file from the module Moodle page and move it to where your README file is.

Go into your project files and delete the ".vs" and "x64" folders from the project files. Now push this all to your repository.

This should now allow you to add, commit and push future changes with visual studio open. It should also not bring in unneeded Build folders when you pull and clone your repository in the future saving on downloading MBs of extra data.

Homework

Make sure you understand how GitHub works. Make sure to git clone your work onto your home computer / laptop so you can work on the project outside of lecture / lab hours.
This will make sure you understand how Git works.

Make sure to git pull when you are on the other machine when you do changes so you have the latest files as your local copy!

Although graphics will not be marked as part of 217CR, you will still need to understand how OpenGL works.

Can you tell which part is responsible for drawing what?
Can you tell what each glut function is for? If you are unsure, look them up on OpenGL deocumentation or ask for help.
The FreeGLUT functions use callbacks. What is a callback?
Why does idle() makes a call to glutPostRedisplay()?
The callbacks currently use functions, such as glutIdleFunc(idle).
Some of these functions are very small (~3 lines). Defining a separate function for this seems like a lot of effort and it can also confuse you as a programmer. It might be worthwhile to not have to specify a function.

Fortunately you can actually do this using lambda functions (since C++ 11). http://en.cppreference.com/w/cpp/language/lambda

Try to re-write some of the glut function calls via lambdas. For example re-write glutKeyboardFunc(keyInput) to not use the keyInput function, but still close when ESC is pressed.

Teaching-Material/Session 1/README.md