A Crash Course In HuC Part 1 - Hello, PCE World!

Search ObeyBrew.Com

OBEYBREW.COM | Tutorials | A Crash Course In HuC Part 1

A Crash Course In HuC

Part 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

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, huc.h.

#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 wont 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. load_default_font 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! put_string here 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!

The usual method of compiling 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);
}