Lode's CG Tutorial

QuickCG Functions

Table of Contents

Back to Index

Introduction

This chapter contains a few easy examples to learn working with QuickCG and explore all its functions.

The previous chapter contained a table with all the functions of QuickCG, but this chapter will provide much more details about these functions.

The main function

QuickCG currently exists out of 6 files:
The main.cpp file begins with including a few headers: QuickCG.h so that the QuickCG functions can be used, SDL.h so that SDL functions can be used, and a few standard C++ headers that come in handy sometimes.

Below these header inclusions is where you can put the code of the examples given in all the articles of this tutorial. Leave the inclusions intact (or add some if you need it).

If the example code has no main function, you have to add it yourself, and then copypaste the example code inside the main function as follows: 

int main(int argc, char *argv[])
{
  // Put the code here
}

If the example requires multiple functions (for example the recursive functions in the recursion trees chapter), a main function is already included in the example so you can simply copypaste everything into the main.cpp file below the header inclusions, and it should compile and run perfectly.

The Basic Screen Functions

The basic screen functions of QuickCG allow you to set up a window, plot pixels on it, view the results and clear it again.

The screen(int width, int height, bool fullscreen, char* text) function sets up the graphical screen. The integers width and height are the width and height of the screen respectively. The boolean fullscreen allows you to choose whether or not you want to go fullscreen: if you set it to 0, the graphical output will be in a window, if you set it to 1, it'll go fullscreen. The string text is the caption or title of the window.

If you want to go fullscreen, you have to make sure you use dimensions your videocard supports, for example dimensions like 640*480, 1280*1024 or 400*300 are supported, but 123*548 isn't. In windowed mode, all resolutions are supported, even something like 1001*23.

After setting the screen, two global integer variables w and h have been set to the width and height of the screen respectively. These variables were given such short names, and are made global, because they're often used in mathematical expressions in the examples, and it's not without reason that in mathematics and science single symbols are used for constants and variables as well.

In screen coordinates, the coordinates (0, 0) represent the top left of the screen, and (w - 1, h - 1) the bottom right. So unlike a mathematical plot, in screen coordinates increasing y represents a lower position.

The pset(int x, int y, ColorRGB color) function plots a single pixel at location x,y with given RGB color: ColorRGB color has 3 components r, g, b which are values between 0 and 255. Make sure that location x, y is actually on the screen, x and y should not be negative and should be smaller than w and h (the width and height of the screen).

The redraw() function uploads all pixels you have drawn to the videocard, so that you can see them. If you only set up a screen and plot some pixels to it, you won't see the pixels yet. Only after using redraw you will. This function is relatively slow though, so don't call it after every single pixel you draw, but only at the end after everything has been drawn.

The void cls(ColorRGB color = RGB_Black) function clears the whole screen at once to the given RGB color. If you give no color, it'll be cleared to black. Normally if you plot pixels, then redraw, then plot some more pixels, and then redraw again, the first pixels will still be there as well if the new pixels were drawn at other positions. If you don't want this, use cls to clear the first pixels.

Here's again the same example of the previous chapter, that uses all these functions (except cls): 

int main(int argc, char *argv[])
{
  screen(256, 256, 0, "Small Test Script");
  for(int x = 0; x < w; x++)
  for(int y = 0; y < h; y++)
  {
    pset(x, y, ColorRGB(x, y, 128));
  }
  redraw();
  sleep();
}

The output looks like this:



The program goes to every pixel of the window, and gives it a different color based on what its coordinates are, giving this color pattern.

Non Graphical Functions

The non graphical functions take care of things like input, program flow, etc...

The sleep() function pauses the program until you press a key, or closes it if you press the close button of the window.

The function void waitFrame(double oldTime, double frameDuration) is made to be handy in cases where you want to limit an effect to a maximum amount of frames per second. The parameter oldTime is the time of the previous frame after calling waitframe that frame, and frameDuration is in seconds per frame. An example of using it could be: 

oldTime = time;
waitFrame(oldTime, 0.05); // 50 milliseconds
time = getTime();

The value oldTime is then always the time of the previous frame after calling waitframe, and the waitframe function will consume the part of the 50 milliseconds that wasn't used up yet by the rest of the code of this frame. This function also uses SDL_Delay internally so that it frees CPU time for other applications.

The bool done() function returns true if the user presses escape or the close button of the window. This function can be used if you want your program to have a main loop that ends if the user wants to quit the program, for example like this: 

screen(256, 256, 0, "Done?");
while(!done())

{
  //do some stuff here

}

The end() function immediately ends the program when called.

The readKeys() function lets SDL check what keys are pressed, and stores the result in an array inkeys[]. You can then check in your program if a key was pressed by checking if keyDown(NameOfTheKey) or keyPressed(NameOfTheKey) is true. keyPressed returns true only once per time the key is held down, while keyDown will keep returning true as long as it's held down. A table with the names of all keys is in the previous chapter or in the SDL reference. For example the "a" key is named SDLK_a and the right arrow SDLK_RIGHT.
Note: when using "done()", then you don't need to call readKeys() anymore because the done() function already calls it and calling it once per frame is enough.

The function long getTicks() returns the time since the program started in milliseconds.

Here's an example that uses all these functions to allow you to move a circle arround with the arrow keys with a certain speed, independent of the processor speed: 

int main(int argc, char *argv[])
{
  screen(400, 300, 0, "Movable Circle");
  float x = w / 2, y = h / 2; //the position of the circle; initially set it to the center of the screen
  float time, oldTime; //the time of the current and the previous loop
  while(!done())
  {
    //set the old time to the time of the previous loop
    oldTime = time;
    waitFrame(oldTime, 0.05);
    time = getTime(); //get the time since program start
    readKeys(); //get the current keystate

    //if an arrow key is pressed, move the circle in its direction at a speed of 50 pixels/second
    if(keyDown(SDLK_RIGHT)) x += (time - oldTime) / 20.0;
    if(keyDown(SDLK_LEFT)) x -= (time - oldTime) / 20.0;
    if(keyDown(SDLK_UP)) y -= (time - oldTime) / 20.0;
    if(keyDown(SDLK_DOWN)) y += (time - oldTime) / 20.0;
    drawDisk(int(x), int(y), 20, RGB_Gray); //draw a grey circle with radius 20 pixels at the position of the ball
    redraw();
    cls(); //clear the screen so the old position of the ball becomes black again
  }
}

First the screen function creates the graphical window. Then some variables are initialized for the position of the ball, and the timing.

Then the main loop starts, the program will keep running and doing the calculations inside the loop until you press escape or use the close button. In this main loop, first the current time is calculated, and the previous time is set in the "oldTime" variable. The time difference t-oldTime can then be used to represent the time that passed between this and the previous loop.

Then the current keystate is gotten with the readKeys function, and the program will then check if the right, left, up or down arrow are pressed, and if one is pressed, change the coordinates of the circle. Since the circle is moved (t - oldTime) / 20.0 pixels, and the time is represented in milliseconds (1/1000th of a second), the circle will move at 50 pixels/second, no matter how fast or slow the computer is.

Finally, the program draws the circle with the disk command (to make it filled), redraws the screen so that you can see it, and then clears the backbuffer so that the next frame can be drawn.

Floating point numbers are used for the position of the circle, because a high precision is required for the timing. In the disk function call, the location has to be converted to integers so that it can be used as screen coordinates though.

The 2D Primitives

The following functions draw primitives like lines and circles on the screen. These are not standard SDL features (except the filled rectangle), but have to be done pixel by pixel. These functions use optimized algorithms to draw the line or circle as fast as possible with pure integer calculations. How these functions work is explained in another chapter of this tutorial. They were also included in QuickCG so that you can easily use them for other programs that need them (like the recursion trees).

bool drawLine(int x1, int y1, int x2, int y2, ColorRGB color) draws a line from point (x1, y1) to point (x2, y2) with the given color using the Bresenham algorithm. Make sure both points are inside the screen, or this function won't draw the line and return 0 (use the clipLine function to clip arbitrary lines to the screen). The line function return 1 if it could draw the line successfully.

bool drawCircle(int xc, int yc, int radius, ColorRGB color) draws a circle with its center at location (xc,yc), and given radius and color. This circle isn't filled. Again, it'll return 0 and draw nothing if the circle had pixels outside the screen, and return 1 if it could draw the circle correctly.

bool drawDisk(int xc, int yc, int radius, ColorRGB color) draws a filled circle with its center at location (xc,yc), and given radius and color.

bool drawRect(int x1, int y1, int x2, int y2, ColorRGB color) draws a rectangle with corners in x1,y1 and x2,y2, with the given color.

bool clipLine(int x1,int y1,int x2,int y2, int & x3, int & y3, int & x4, int & y4): Use this function if you need to bring the endpoints of a line (or corners of a rectangle) you're trying to draw to the inside of the screen. Give the function a line with coordinates (x1,y1)-(x2,y2), and it'll return a line with coordinates (x3,y3-x4,y4) that are on the edges or inside the screen, that is, inside the rectangle (0,w)-(0,h). The variables x3, y3, x4 and y4 have to be given to the function by reference, so for example use clipLine(x1, y1, x2, y2, x3, y3, x4, y4), where x3, y3, x4 and y4 are normal integers that can be changed by the function, to give the coordinates of the new line to those variables. The function returns 1 if the line is on the screen and 0 if the line isn't on the screen.

The following example will draw a clipped line on screen, and then also a circle, disk and rectangle to show these commands in action as well. 

int main(int argc, char *argv[])
{
  screen(400, 300, 0, "2D primitives");
  int x1, y1, x2, y2; //The initial line, too big for the screen
  int x3, y3, x4, y4; //Will become the clipped line
  x1 = -50; //This is outside the screen!
  y1 = -20; //This is outside the screen!
  x2 = 1000; //This is outside the screen!
  y2 = 1200; //This is outside the screen!
  clipLine(x1,y1, x2, y2, x3, y3, x4, y4); //the new line represents the part of the old line that is visible on screen
  drawLine(x3, y3, x4, y4, RGB_Red); //The newline is drawn as a red line
  drawCircle(100, 100, 30, RGB_Green); //a green unfilled circle
  drawDisk(200, 100, 20, RGB_Yellow); //a yellow filled circle
  drawRect(150, 150, 200, 200, RGB_Cyan); //acyan square
  redraw(); //make it all visible
  sleep(); //pause
}

The output is as follows:


Color Conversions

These functions change the representation of a color from one color model to another. The RGB model is used by the computer and the screen, while the HSL and HSV color models are more intuitive for a human to select a color. These functions aren't a feature of SDL but are explained somewhere else in this tutorial, but were included in QuickCG so that you can easily use them in other programs to get nice color gradients (for example to draw pretty fractals or plasmas). More info on color models is in the color chapters of this tutorial.

The 4 color model conversion functions are:

ColorHSL RGBtoHSL(ColorRGB colorRGB);
ColorRGB HSLtoRGB(ColorHSL colorHSL);
ColorHSV RGBtoHSV(ColorRGB colorRGB);
ColorRGB HSVtoRGB(ColorHSV colorHSV);

Every color model has 3 parameters to describe the color. The ColorRGB, ColorHSL and ColorHSV data types are all just dumb structs with 3 integers, the only difference there is the names of the integers. The conversion functions allow you to calculate the components of the returned color model out of the given color model.

As an example, let's use both the HSLtoRGB and the HSVtoRGB functions to compare the HSL and HSV color model with each other. More info on how these functions work is in the Light and Color chapter. 

int main(int argc, char *argv[])
{
  screen(512, 256, 0, "HSL versus HSV");
  ColorRGB color;

  for(int x = 0; x < 256; x++)
  for(int y = 0; y < h; y++)
  {
    color = HSLtoRGB(ColorHSL(x, 255, y)); //convert the color "hue=x, saturation=255, lightness=y" to RGB
    pset(x, y, color); //plot a pixel from the HSL model
    color = HSVtoRGB(ColorHSV(x,255, y)); //convert the color "hue=x, saturation=255, value=y" to RGB
    pset(x + 256, y, color); //plot a pixel from the HSV model
  }
  redraw();
  sleep();
}



First using RGBtoHSL and then using HSLtoRGB on the result again, gives the original values back.

There are also the functions Uint32 RGBtoINT(ColorRGB colorRGB) and ColorRGB INTtoRGB(Uint32 colorINT) which convert the RGB color to and from a single integer value.

Image Loading

QuickCG has a function that can load PNGs: loadImage. There are two versions of it, one that stores the image in a ColorRGB array, and another version that stores the image in a Uint32 array where the RGB color of each pixel is stored in a single 32-bit integer per pixel.

int loadImage(std::vector<ColorRGB>& out, unsigned long& w, unsigned long& h, const std::string& filename); The function will return 0 if it successfully loaded the image and 1 otherwise.
For example to use this function to load a 64*64 PNG file, type: "std::vector<ColorRGB> image; unsigned long w, h; loadImage(&image, &w, &h, "filename.png");"

The other version of this function is int loadImage(std::vector<Uint32>& out, unsigned long& w, unsigned long& h, const std::string& filename);. This one stores the color as a 32-bit integer, instead of ColorRGB.

The following example will load an image "test.png" of 128*128 pixels and draw it on the screen. To get the program to work, you have to put such an image in the same folder as the compiled binary of course (or else use full paths). 

int main(int argc, char *argv[])
{
  std::vector<ColorRGB> image;
  unsigned long w, h;
  if(loadImage(&image, &w, &h, "filename.png")) return 1;
  screen(w, h, 0, "An image");

  //draw each pixel of the image
  for(int y = 0; y < h; y++)
  for(int x = 0; x < w; x++)
  {
    pset(x, y, image[y * w + x]);
  }

  redraw();
  sleep();
}



If you want to use a single array to contain multiple textures, then the parameter that represents the number of the current texture has to be the first one of the array. You can then use it normally with the loadBMP function separately for each texture, but have to add the extra array parameter with the number of the texture.

Text Functions

QuickCG has a built in font, it doesn't have to load any image or file containing the font, the font is a boolean array, bool font[256][8][8], completely defined in the code. This font is the ASCII charset of IBM computers, containing 256 characters of each 8*8 pixels. Here's the full ascii chart, with the hex code of each character included, e.g. the symbol "j" has hex code A6, or in decimal: 166.



int printString(const std::string& text, int x = 0, int y = 0, const ColorRGB& color = RGB_White, bool bg = 0, const ColorRGB& color2 = RGB_Black) draws a normal string of text. There are a lot of parameters with default settings, so that you don't have to type all these parameters if you're satisfied with the defaults.
When the text is too long and reaches the right side of the screen, the position will jump one line lower and to the left of the screen again. If it reaches the bottom, it'll continue at the top left of the screen.

The return value is h * x + y where x is x position of next letter, y is y position of next letter and h is height of the screen. This return value is useful to find the start location for a possible next print command that should be behind the previous text: x coordinate is then "returnValue / h", y coordinate is "returnValue % h". See the example below how this works.

The print function allows printing arbitrary variable types (as long as they can be converted to std::string using a std::stringstream). Apart from the value, it shares the same parameters as the printString function.

template<typename T> int print(const T& val, int x = 0, int y = 0, const ColorRGB& color = RGB_White, bool bg = 0, const ColorRGB& color2 = RGB_Black, int forceLength = 0)):

void drawLetter(unsigned char n, int x, int y, const ColorRGB& color = RGB_White, bool bg = 0, const ColorRGB& color2 = RGB_Black); Prints a single character given its ascii code.

Using the return value of the print functions is handy if you want to draw multiple texts behind each other and don't want to update the coordinates manually each time you change the texts (making it longer or shorter), or if you print a number and don't know yet how long it'll be and want to print something behind it. This is used in the "All your base..." part, pos is set to the return value of the print function every line and used for the parameters of the next line.

Here's an example that uses all these functions. 

int main(int argc, char *argv[])
{
  screen(256, 256, 0, "Text");
  //draw some texts
  print("Hello World!");
  print("I am spooky green text!", 20, 20, ColorRGB(0, 255, 0), 1, ColorRGB(0, 128, 0));

  //draw an integer variable
  int number = 1337;
  print(number, 16, 40, ColorRGB(0, 255, 255));

  //draw a floating point variable
  float pi = 3.1415926535897932384626433832795;
  print(pi, 0, 8);

  //draw every single character of the font
  for(int x = 0; x < 16; x++)
  for(int y = 0; y < 16; y++)
  {
    drawLetter(x + 16 * y, 100 + x * 8, 100 + y * 8, ColorRGB(255, 255, 255), 1, ColorRGB(255, 0, 0));
  }

  //draw multiple texts in a row easily by using the return value
  int pos;
  pos = print("All", 0, 70, RGB_Red);
  pos = print("your", pos / h, pos % h, RGB_Green);
  pos = print("base", pos / h, pos % h, RGB_Blue);
  pos = print("are", pos / h, pos % h, RGB_Yellow);
  pos = print("belong", pos / h, pos % h, RGB_Cyan);
  pos = print("to", pos / h, pos % h, RGB_Magenta);
  pos = print("us!!", pos / h, pos % h, RGB_White);

  redraw();
  sleep();
}

And it outputs the following:

Text Input

The text input functions allow you to enter a string or other variable type from within the program. The commands print the message at given position with the given color and background, and allow you to type the char, string or number after the message.

The following example shows how to use the functions: 

int main(int
argc, char *argv[])
{
  screen(256, 256, 0, "Input Text");
  //input a string
  std::string someText;
  getInputString(someText, "Enter some text:", false, 0, 0);
  //input an integer
  int someInteger = getInput<int>("Enter an integer:", false, 0, 8);
  //input a double
  double someDouble = getDouble<double>("Enter a number:", false, 0, 16);
}

Here's the result after typing something and pressing enter 3 times (after the third enter the program closes):


(deprecated screenshot)

drawBuffer

The drawBuffer(Uint32 *buffer) function draws a whole 2D array of pixels at once. This is much faster than using pset for every pixel separately.

The buffer to draw has to be a 2D array with exactly the same size as the screen, and with the RGB color values stored in a single integer. To convert an RGB color to the integer value, use colorINT = B + 256 * G + 256 * 256 * R. To convert it back to RGB, use R = (colorINT / 65536); G = (colorINT / 256) % 256; B = colorINT % 256. This is exactly what the RGBtoINT and INTtoRGB functions do.

So create the array with 

Uint32 buffer[h][w];

(note that the height coordinate is first, because it works per scanline in memory) and after filling it with colors, draw it with 

drawBuffer(buffer[0]);

If you're emulating a palette, it's handy to create the palette's colors in the BGR order in an integer as well, an example of this is in the Fire Effect article.

Last edited: 12 August 2007

Copyright (c) 2004-2007 by Lode Vandevenne. All rights reserved.