Lesson 1: Hello PCE World!

Virtually all introductory programming texts start with a "Hello World!" example, so why break tradition now? :) But unlike many other programming texts that bore the hell out of you from the start with useless theory, we're going to jump straight into programming useful things from the very first lesson. Since this is the first lesson, I'm going to keep it rather simple: we'll be making a very simple ROM image that will run in any emulator.

What You'll Learn

In this lesson, you'll learn how to set up a HuC program and how to put some text on the screen.

The First Step

If you're using HuiCide, create a new HuCard project. When the template dialog comes up, choose "Blank Project". We'll be creating a blank project because you'll need to know the basic structure of a HuC program. Once you grasp the concepts, feel free to use the templates to save some time. Once you have your project created, be sure to save it. Save the "source" file as "hello.c" and the "project" file as "hello.huc".

If using Notepad or similar editor, create a new file and save it as "hello.c". Make sure this file is saved as plain text...as much as some word processors make some very pretty text, the compiler won't be able to understand the special formatting that they use, so make sure you do not format the text in any way! That means NO colors, NO font changes, NO bold, NO "justify", NO tables, or any of that kind of fancy stuff...just good old text.

Writing Our Program

The Two Most Important Pieces Of The Puzzle

The very first step in our program is what is called an "inclusion", or more commonly just called an "include". This simply means we're going to include something else into our program. In this case, we are going to include the "HuC header".

#include "huc.h"

So...what does this do? Well, this includes the header file for the "HuC Standard Library", which contains all the definitions for the functions that we'll be using later on. Without this line at the top of your program, your program won't work...at all.

The other critical part of every program you write is what is called "the main function". The main function is where your program starts. Clever name, huh? :)

main()
{

Take note of two main details here. First of all, the word "main" is followed by parenthesis (). This tells HuC "hey, this is a function right here, so you better recognize!". On the next line, we see the "curly bracket", or {. Think of this as an "enclosure". Later, we will use its inverse, the }. Why do we do this? Well, in the C programming language, { and } are used to enclose sections of code. Every function starts with { and ends with }.

Making Something Happen

What we have so far isn't very impressive...in fact, it doesn't really do anything we can see. So let's make our machine do some work we can see!

  set_color_rgb(1, 7, 7, 7);

Okay, so what does this do? Well, as the name suggests, it sets a color. "set_color_rgb" is a function in the HuC standard library. Remember when we included "huc.h"? Well, that allows us to use functions like this one. Let's take a look at the details of this line.

First of all, notice the parenthesis that enclose four numbers. When using a function, we need to use (), sort of like how we made the main function. Notice that this line has a ; on the end of it, but main() does not. The ; character means "okay, this is the end of this line of code". So why doesn't main() have one at the end of it? Well, because when you make a function, you can't put the ; at the end of the line...otherwise, the compiler will think you're trying to actually CALL the function you're writing! So when you write the start of a function, you don't use it. But when you call a function, you do. Make sense? :)

Now, let's make note of the values themselves. set_color_rgb takes four pieces of data, called "arguments" (no, functions do not argue with each other, and I have no idea why they called them this..."parameters" would be a better phrase, right?). This function alters a color in the palette. There are 512 color "indexes" on this hardware, the details of this are covered later, as well as in the normal reference. Anyways, we're telling the hardware "hey, we're going to change color 1". The next arguments are the pieces of data that determine the actual color. If you remember from art class, color is made up of three primary colors: red, blue, and yellow. However, the rules are slightly different when it comes to light: all colors in regards to light are made up of red, blue, and green. Furthermore, in color terms, the more pigment you use, the darker the color. In light, the opposite is true: the more light you use, the brighter the light. In our case here, we can use values between 0 and 7 for each of the three primary colors: red, green, and blue. When mixed together evenly, we get a grey. When we use all 7s, we get pure white.

If you've grasped this stuff, then the rest will be easy. :)

  set_font_color(1, 0);

Now we're starting to get somewhere here. "set_font_color" is a function that defines the "foreground" and "background" of the text we're going to put on the screen in a little while. The first argument says "hey, make sure the letters are drawn in color 1 of the palette we're going to use". Remember that we set color 1 to pure white just a moment ago? Color index 1 is also color index 1 of the first palette on the machine, palette 0 (more on this in a minute). The second argument says "and set the background to color 0". Color 0 will be all 0s by default, or pure black.

  set_font_pal(0);

We could get into the hard details about palette arrangements and how palette sets relate to the range of indexes in the palette, but that's a subject for a later time. :) For the time being, recognize that this particular function sets the number of the palette, in this case, palette #0. Color index 1 is part of palette 0. If we were using palette 1, we'd use color index 17 for set_color_rgb instead, if we were using palette 2, we'd use color index 33 instead, etc etc etc right up to palette 15.

  load_default_font();

Finally, a function with no arguments! :) This function loads the default font and gets us ready to finally put something on the screen. Everything we've set up so far will show once we use our final function of this lesson...

  put_string("Hello PCE World!", 8, 13);

Finally, text on the screen! :) This prints out "Hello PCE World!" in the middle of the screen. There are three arguments: the first is the text itself, the second is the number of characters across, and the third is the number of characters down. Keep in mind that the screen, by default, is made up of 32 characters across and 28 characters down. We can change this later if we want, but most software written for this machine uses this default setup.

Easy stuff, right? Wait a second though...it seems we forgot something. Our function is complete, but we have to "end" it. Remember how?

And just like that...our very first PCE program is complete!

Compiling And Running Our Program

Before you do anything else, SAVE YOUR WORK! :)

HuiCide makes the compiling process painfully easy: click Compile And Run. If HuiCide is configured for an emulator, and there are no errors in your code, then the program will be compiled and your emulator will come up with your program running in it. If not, then either you need to configure HuiCide for an emulator, or make corrections to your code (HuiCide will show you where the errors are).

If compiling manually, the usual method is to type huc hello.c on the commandline, or by dropping hello.c on top of huc.exe in Explorer.

If all goes according to our diabolical plans, what you end up with is a file called "hello.pce". This is an executable ROM image that an emulator can understand.

So...What's Next?

This lesson has covered a great deal of material in a very short time. You should now understand the basic essentials for writing a HuC program: the header file, the importance of the main function, how functions are called, how arguments are used, and how to write a simple function. But we've only barely scratched the surface. The next lesson will cover more text writing functions and introduce you to the wonderful *cough* world of variables. :)

Full Program Listing

#include "huc.h"
main()
{
  set_color_rgb(1, 7, 7, 7);
  set_font_color(1, 0);
  set_font_pal(0);
  load_default_font();
  put_string("Hello PCE World!", 8, 13);
}