h

The Instinct Graphics Package

The Instinct Graphics Package is an easy to use and free 2D graphics programming framework for C++.  It can be used simply to output something to a screen or as a package for making 2D games.  It is completely free to use whether it is for personal use or for educational purposes. For educational use or for general questions, feel free to contact us ratadero@predatorinteractive.com

Tutorials and Videos

For videos and tutorials on installing and using the Instinct Graphics package, click here.

h

Installing The Instinct Graphics Package – Windows

Before we can use the Instinct Graphics Package on Windows, let’s go ahead and get ourselves a nice programming environment and then get the Graphics Package resources.

Installing the Code::Blocks IDE with the MinGW C++ Compiler

So first thing is first, let’s download Code::Blocks with the bundled C++ Compiler so we have a place to make our programs.

To download the Code::Blocks IDE and MinGW Compiler: Click Here

Go ahead and walk through the simple installation steps and once that is done let’s try making a sample C++ program.

Using Code::Blocks

So once you have fully installed Code::Blocks and the MinGW compiler, go ahead and click “New->Empty File”.  A blank file should pop up for you to write your own C++ program.  Go ahead and write a Hello World program in there to make sure everything installed and is working correctly.

#include <iostream>

using namespace std;

int main()
{
    cout << "Hello World" << endl;
    return 0;
}

Once you have finished typing this, go ahead and click on the button that looks like  which will compile and run your program.

It will ask you to save the file,  just put it anywhere and call it “main.cpp”.  Don’t worry about putting it in a special place for now, you can delete this file once we are done here.

If you happened to have a compiler error, Code::Blocks will show you, just go ahead and fix it and press build and run again until there are no more errors.

When your Hello World program runs, you should see something similar to this:

If you see the words Hello World in a terminal, then you have successfully installed Code::Blocks and the MinGW compiler!

Wait, I Can’t Get My Program To Work, It Keeps Saying Cannot Find mingw32-g++.exe

If your program wont even attempt to compiler or run and you get a message similar to the one above, then something probably went wrong with your installation.  First thing to check is to see if Code::Blocks knows where the MinGW compiler is at.

Go ahead and click “Settings->Compiler and Debugger”.  In the window that pops up, click the “Toolchain Executables” tab.  There will be a section for the Compilers installation directory.  Go ahead and click “auto detect” and make sure the path listed there exists on your computer.  If it does not exist, perhaps you installed this on another disk drive and should try to find it on there and point Code::Blocks there if you can find it.

If after all that things still don’t work, perhaps the installation itself just failed and go run the installer once again and remember where you told it to install.

Getting the Instinct Graphics Package

Instinct Graphics Package Project Folder: Download Here

h

Basic Commands and Drawing Shapes

First thing is first when trying out the Instinct Graphics Package. Let’s learn what is needed to be set up prior to drawing anything.

Starting Code to Use

To begin coding a Instinct Graphics Package program, you must first have at least this starting code set up:

#include "instinct.h"

int instinct_main()
{
    return 0;
}

The Instinct Project folder will have this already precoded.  However if you are coding this from scratch you must type the code above.

The “instinct_main()“ function acts similar to the standard “int main()“ function that console programs use.

Shapes

There are different ways to draw shapes to the screen. The shapes we can draw are:

• Point
• Line
• Circle
• Rect
• Triangle
• Message

The constructors you can use for each are as follows:

• Point(double x, double y)
• Line(Point start, Point end)
• Circle(Point center, double radius)
• Rect(Point lower_left, double width, double height)
• Triangle(Point p1, Point p2, Point p3)
• Message(Point lower_left, string text)

Colors

The Colors that are available to use on the shapes are:

The default color for shapes is BLACK. Each object can use the “set_color(Color color)“ member function to change their color.
Example:

• pt.set_color(BLUE);
• line2.set_color(GREEN);
• circ.set_color(YELLOW);
• etc.

Or you can add an extra parameter to the end of any of the shape constructors to specify their starting color instead.
Example:

• Circle circ = Circle(Point(5, 5), 2, YELLOW);
• Line l2 = Line(Point(0, 0), Point(5, 5), ORANGE);

Filling in Objects with Color

All the objects except the Line can either be outlined or filled in with color. To set whether a object is filled in with color or not, you can use the “set_filled_in(bool is_filled)“member  function.
Example:

• circ.set_filled_in(true);
• rect.set_filled_in(false);
• etc.

So the Circle circ will be filled in with it’s color while the Rect rect will only be outlined with it’s color.

Similarly to the colors, you can add that parameter to the end of a constructor if the constructor already has the color included.
Example:

• Circle circ = Circle(Point(5, 5), 2, YELLOW, true);
• Rect rect = Rect(Point(1, 2), 5, 5, BLUE, true);

So both the Circle circ and the Rect rect will be filled in with color since they added true after the color argument in their constructors.

The “win” Object

When it comes to manipulating the window or drawing shapes to the window, you must use the “win” object that is already created.  We will use the “win” object to draw shapes, change the background color, get user input, play audio, etc.

Drawing and Outputting Shapes

To actually draw shapes to the window, first you have to add them to the window buffer. You do this by using the insertion operator on the “win” object.
Example:

• win << circ;
• win << rect;

This adds the Circle circ and then the Rect rect onto the windows drawing buffer. You can add more than one object to the buffer at a time.
Example:

• win << circ << rect << line2;
• win << pt << triangle;

Then once you are ready to draw everything in the buffer, use the “win.output_buffer()” command to output everything in the buffer to the screen.
Example:

• win << circ << rect;
  win << line3 << pt2;
  win.output_buffer();

The above example in lines 1 and 2 add Circle circ, Rect rect, Line line3, and Point pt2 onto the buffer to be drawn.  Then the final line outputs all of the shapes that we just put in the buffer (as well as any other shapes that were previously in the buffer) onto the screen all at once.

Changing the Background Color

To change the background color of the window, you must use the “win.set_background_color(Color color);“ function.
Example:

• win.set_background_color(BLACK);
• win.set_background_color(RED);

So the first example above will change the background color of the window to BLACK. Be careful when changing the background that you do not draw any shapes the same color as the background. If you set the background to BLACK, any BLACK shapes won’t be seen on the background.

Changing the Title on the Program

The last little thing you can do to your program is change the title of your window. You do this by using the “win.set_title(string new_title)“ function.
Example:

• win.set_title(“My Cool Program”);
• win.set_title(“Space Wars!”);

So that’s all the basics for drawing shapes, colors, outputting, and changing the title.

h

Getting Basic User Input

There are four main ways to pause the program and ask the user for a value.

• Getting an int value
• Getting a double value
• Getting a string value
• Getting a point on the screen

Getting an int value

To ask for an int, use the function: win.get_int(string prompt);
Example:

• int age = win.get_int(“How old are you?”);
• int radius = win.get_int(“Enter a value for the radius.”);

In example 1, the program will pause and display the message “How old are you?” at the top of the screen. The user will then type in a numerical value and press enter.  That value typed will then be returned and stored in the variable age.

Getting a double value

To ask for a double, use the function: win.get_double(string prompt);
Example:

• double price = win.get_double(“How much does the car cost?”);
• double mass = win.get_double(“How much does the ball weigh?”);

In example 1, the program will pause and display the message “How much does the car cost?” at the top of the screen. The user will then type in a numerical double value and press enter.  That value typed will then be returned and stored in the variable price.

Getting a string value

To ask for a string, use this function: win.get_string(string prompt);
Example:

• string name = win.get_string(“What is your name?”);
• string part = win.get_string(“Which part would you like to buy?”);

In example 1, the program will pause and display the message “What is your name?” at the top of the screen. The user will then type in a string value and press enter.  That value typed will then be returned and stored in the variable name.

Getting a Point on the screen

To ask for a point on the window, use this function: win.get_click(string prompt);
Example:

• Point location = win.get_click(“Click where you want to start.”);
• Point end_point = win.get_click(“Click on the screen for the end point of the line to make.”);

In example 1, the program will pause and display the message “Click where you want to start.” at the top of the screen. The user will then click a location on the screen.  That Point location on the screen will be returned and stored in the variable location.

Changing the color of the displayed message

Similar to  drawing objects, you can also specify a color for all the prompts. The default color is BLACK. To set the color of the prompts, just add a color to the end of the function.
Example:

• win.get_int(“How old are you?”, BLUE);
• win.get_double(“What is the weight of the ball?”, GREEN);
• win.get_click(“Click where you want to start.”, WHITE);

So for example 1, the message “How old are you?” will be displayed at the top of the screen in the color BLUE instead of BLACK.

Those are all the basics for getting user input. Soon it will be Instinct to you!

h

Clearing the Screen and Functions for Shapes

Here is a quick overview of how to clear the screen and other functions you have for shapes.

Why Do We Need To Clear the Screen?

So what exactly do we mean by clearing the screen.  Well if we did the following code:

win << Circle(Point(5, 5), 2);
win.output_buffer();

Naturally we will draw a circle to the screen.  But if we do the following code right afterward:

win << Rect(Point(2, 2), 3, 3);
win.output_buffer();

It will then draw a Rectangle to the screen.  However, the circle we initially outputted will still be on there as well. If we want to only have the Rectangle on the screen by itself, we have to clear the circle that we drew before hand. To do that, we need to make sure the buffer is empty prior to inserting the Rect object.

Clearing the Screen

To clear the buffer we use the following function: win.clear_buffer();

This will clear all of the objects off of the buffer so we can begin inserting new ones to draw.  So now if we do the following code:

win << Circle(Point(5, 5), 2);
win.output_buffer();

win.clear_buffer();
win << Rect(Point(2, 2), 3, 3);
win.output_buffer();

First the circle is added to the buffer and drawn to the screen.  Then everything will be cleared from the buffer with win.clear_buffer().  This does NOT clear the screen, this just clears the drawing buffer.  Then the Rect is added to the empty drawing buffer.  And then finally, the Rect is outputted to the screen by itself with the second call of win.output_buffer();

More Functions for Shapes

Every shape in the Instinct Graphics Package can use the following functions:

• obj.move(double dx, double dy);
• obj.get_color();
• obj.is_filled_in();
• obj.set_visibility(double percent);
• obj.get_visibility();
  

You can also use these functions below which were covered in Tutorial 2. Basic Commands and Drawing Shapes.

• obj.set_color(Color color);
• obj.set_filled_in(bool is_filled);

Function: obj.move(double dx, double dy);

Definition: Moves the shape dx units in the x direction and dy units in the y direction.

• circ.move(5, 4);
• message.move(-2, 3);
• triangle.move(0, -1);
  

So for the first example, we moved the Circle circ 5 units in the x direction and 4 units in the y direction.

Function: obj.get_color();

Definition: Returns the color of the shape.

• if(circ.get_color() == YELLOW)
  
• Color rect_color = rect.get_color();
  

So for the first example, the if statement is true if the color of circ is YELLOW.

Function: obj.is_filled_in();

Definition: Returns whether or not the shape is filled in with color.  True means it is filled in, false means it is outlined with color.

• rect.is_filled_in();
• if(circ.is_filled_in())

The first example returns true if the Rect rect is filled in, and false if it is just outline with color.

Function: obj.set_visibility(double percent);

Definition: Sets the visibility of the shape to the percent amount passed in.  A percent value of 1.0 means the shape is fully visible (100% visible). A percent value of 0.5 means the shape is half visible (50% visible). A percent value of 0.0 means the shape is fully invisible (0% visible).

• circ.set_visibility(0.75);
• message.set_visibility(0.10);

The first example sets the visibility of circ to 75%.  So the Circle circ is parcially see-through but mostly visible.

Function: obj.get_visibility();

Definition: Returns the visibility amount of the shape.

• if(circ.get_visibility() == 0.0)
• rect.set_visibility(rect.get_visiblity() - 0.1);

The first example, the if statement is true if the visibility of circ is 0.0 (invisible).

Functions Specific to each Shape

Each shape also has its own set of specific functions that it’s shape type.  In other words, there are functions specific to Rects and functions specific to Circles, etc.  So let’s look at all of those:

Point

The Point shape has these specific functions it can call as well:

• pt.get_x();
• pt.get_y();
• pt.set_x(double new_x);
• pt.set_y(double new_y);

Circle

The Circle shape has these specific functions it can call as well:

• circ.get_center();
• circ.get_radius();
• circ.set_radius(double new_radius);
• circ.set_center(Point new_center);

Line

The Line shape has these specific functions it can call as well:

• line.get_start();
• line.get_end();
• line.set_start(Point new_start);
• line.set_end(Point new_end);

Triangle

The Triangle shape has these specific functions it can call:

• tri.get_p1();
• tri.get_p2();
• tri.get_p3();
• tri.set_p1(Point new_p1);
• tri.set_p2(Point new_p2);
• tri.set_p3(Point new_p3);

Message

The Message shape has these specific functions it can call:

• message.get_text();
• message.get_lower_left();
• message.set_text(string text);
  message.set_text(int text);
  message.set_text(double text);

h

Window and Coordinate Resizing

So we have seen how to draw the basic shapes and how to get user input to build some more interesting programs.   Now let’s figure out how to modify our coordinate window and the physical window size.

Setting the Coordinate System

If you remember from before, our default coordinate system is (0, 0) in the bottom left corner, and (10, 10) in the top right corner.

We do have a function for changing the coordinate system:
win.coord(double ll_x, double ll_y, double ur_x, double ur_y);
Example:

• win.coord(0, 0, 10, 10); //Default coordinate system
• win.coord(0, 0, 50, 50);
• win.coord(-124.5, 76, 92.4, -33.7);

So for example three up there, our coordinate system would be this after that call:

So the first two values of win.coord(ll_x, ll_y, ur_x, ur_y) are the X and Y of the lower left corner of the coordinate system on the screen and the second two values are the X and Y of the upper left corner.

Changing the Screen Size

As you have probably noticed, our default physical window is a square:

The default size of our window is 500 pixels for the width and 500 pixels for the height.

If you ever want to change the size of your window, (not the coordinate system), you can use this function: win.set_window_size(int width, int height);
Example:

• win.set_window_size(500, 500); //Default window size
• win.set_window_size(800, 600);
• win.set_window_size(1280, 720);

If you are looking for a decent wide window size, standards like 800 x 600, 1024 x 768, 1280 x 720 are good sizes to use.

To get an idea of what resizing the window would do, here is what the window would look like after running the second example above (800 x 600):

Ut oh! The window looks bigger but the circle no longer looks correct.  The reason is because we stretched the window without changing our coordinate system.

Choosing Coordinate Systems for Certain Window Sizes

To get the best results, you should use window sizes and coordinate sizes that are of the same ratio.

The reason the default window size and coordinate size look alright is because both are ratio 1 : 1.

• Default Coordinate System: 10 by 10.  10 / 10 =>  1 / 1 =>  1 : 1
• Default Window Size: 500 by 500.  500 / 500 =>  1 / 1 =>  1 : 1

Since both the coordinate system and window size are of the same ratio 1 : 1, everything drawn looks normal.

But why did it look stretched when we changed the window size to 800 x 600?

• Default Coordinate System: 10 by 10.  10 / 10 => 1 / 1 =>  1 : 1
• New Window Size: 800 by 600.   800 / 600 => 4 / 3 =>  4 : 3

The reason the circle looked stretched was because the coordinate size and window size had different ratios. 1 : 1 and 4 : 3

Solution? Choose a coordinate system that has the same ratio as your window.

win.coord(0, 0, 40, 30); //Change the coordinate system

• New Coordinate System: 40 by 30.  40 / 30 => 4 / 3 =>  4 : 3
• New Window Size: 800 by 600.   800 / 600 => 4 / 3 =>  4 : 3

Now our coordinate system and window size have the same ratio 4 : 3! Draw a circle in the center of our new coordinate system.

• win << Circle(Point(20, 15), 5, BLUE, true);

Viola! Everything looks normal again!  So now you know how to change your coordinate window and your physical window size. And remember! Try to use the same ratios for both to make things draw proportionally correct!

h

All the basics about where to put your images, how to draw them, and helpful hints about transparency.

Image Types

JPEG – Does no transparency.

GIF – Does either full transparency or full opaque.

PNG – Does any level of transparency and opacity.

h

Basic Animation and Timers

Prior to actually getting into the animation code, let’s take a quick look at timers.

Timers

To create a timer which has a time value of zero, simply type: “Timer name_of_timer;“
Example:

• Timer animation_timer;
• Timer stopwatch;

The basic functions of timers are as follow:

• timer.start(); //Makes the timer starting ticking.
  
• timer.stop(); //Stops the timer from ticking.
• timer.reset(); //Resets the time value of the timer to zero regardless if it is running or not.

To get the number of milliseconds on the timer, use the member function: “timer.get_time();“
Example:

• int milliseconds = timer.get_time();
• win << Message(Point(5, 5), timer.get_time());
• if(timer.get_time() > 1000)

To add time to the timer use the “timer.add_time(double milliseconds);“ member function.
Example:

• timer.add_time(20000);
• timer.add_time(penalty_time);

To check if the time has passed some number of milliseconds use: “bool timer.has_passed(double milliseconds);“
Example:

• if(timer.has_passed(15000));
• bool passed = timer.has_passed(10500);

Wait for

You can also use the “wait_for(double milliseconds)“ function which makes the program wait for the passed in number of milliseconds.
Example:

• wait_for(10000); //The program will wait here for 10 seconds.
• wait_for(delay_time); //The program will wait here for delay_time milliseconds.

Remember, there are 1000 milliseconds in 1 second.

Animation

To better understand animation, here is a general definition: Seeing a series of rapid pictures that gives the illusion of movement.

Frames

We are going to call these individual pictures that create this illusion of movement frames. So for example here are a series of four frames:

Now if we show each of these frames one after another with a small pause in between, we will see what looks like a ball moving. This illusion is the basis behind animation!

Now that we hopefully have a better understanding of how animation works, we can put it to use with the Instinct Graphics Package.

Coding Animation

Well we could code the above example by simply drawing a ball, moving it and redrawing it.  If we did that four times in our code with a wait_for(100); in between each of those to cause a slight pause, we could reproduce the moving blue ball easily.
Example:

Circle circ = Circle(Point(1, 5), 1, BLUE, true);

//Frame 1
win << circ;
win.output_buffer();

//Frame 2
wait_for(100);
circ.move(1, 0);
win.clear_buffer();
win << circ;
win.output_buffer();

//Frame 3
wait_for(100);
circ.move(1, 0);
win.clear_buffer();
win << circ;
win.output_buffer();

//Frame 4
wait_for(100);
circ.move(1, 0);
win.clear_buffer();
win << circ;
win.output_buffer();

As you can see above, the frames 2-4 become very much the same. If we wanted more frames we would have to continue copying and pasting the same code for each frame.

Using loops

However, if we use a loop that moves everything and redraws it each time, we could have as many frames as we want without having to continuously add code for each frame.
Example:

win << circ;
win.output_buffer();

while(true)
{
    wait_for(100);
    circ.move(1, 0);
    win.clear_buffer();
    win << circ;
    win.output_buffer();
}

With the while(true), the program will continuously run that loop until we close the program.  So now the loop will continously do frame after frame of moving the ball and redrawing it.

Frame Rate

As you can see above, we were using a value of 100 as the number of milliseconds to wait in between each frame.  This in practice is not a nice number to use since that only allows us to have around 10 frames per second (FPS), which is not a good number.  Generally speaking, a good frame rate for animated programs is usually in between 60 and 30 frames per second.  Because of that, I would suggest using a wait_for amount of 20 milliseconds, which in turn creates a frame rate of around 50 FPS.

• wait_for(20);

Just keep in mind that this wait_for(20); by itself is not the best way to do timing for animation, but it is the simplest.  Later we will go over better and more advanced forms of doing timing for animation loops.

Sectioning the Animation Loop

The last bit of advice I would suggest is to always split up the animation loop into two sections to make sure it is done right:

while(true)
{
    wait_for(20);

    ///////////////////
    // Handle Logic
    ///////////////////
    circ.move(1, 0);

    ///////////////////
    // Draw Everything
    ///////////////////
    win.clear_buffer();
    win << circ;
    win.output_buffer();
}

There should be two distinct sections, the section that handles all the logic of the animation (moving objects, doing collision detection, changing colors of objects, etc), and a section that simply draws everything that needs to be drawn.  So what does this mean?  There should be NO drawing of objects in the Handle Logic section, and only code that deals with the drawing of objects in the Draw Everything section.  If you code is sectioned properly and done correctly, your animation should come out nice and smooth and work perfectly with no flickering.

What Now?

Now the rest is up to you in terms of what you want to do in this animation loop.  You don’t have to have a ball that moves around solely in the X direction.  This was merely an example. You can use Rects, Circles, Images, etc. to make anything you can think of.