AGS Pointers for Dummies: Difference between revisions

Jump to navigation Jump to search
*>Monkey 05 06
No edit summary
Line 1: Line 1:
=AGS Pointers for Dummies (A reference for the rest of us!)=
=AGS Pointers for Dummies (A reference for the rest of us!)=


So you're new to Adventure Game Studio (at least new to version 2.7 or later) and you're a bit confused about all this "pointer" business? Or maybe you've read the manual, but you just don't get it? Don't worry, you're not alone. A lot of people are confused about pointers. That's why I'm here to help.
If you're reading this, then you've come looking for answers. ''What are pointers? How do I use them? What makes them better than just using integers?'' These questions, amongst others shall be answered. You're not alone in the confusion caused by pointers. Many people who are new to scripting, or haven't ever used a language that supported pointers don't understand them right away. That's why I'm here to help.


==What Are Pointers?==
==What Are Pointers?==
''So what exactly are pointers?''
''So what exactly are pointers?''


The basic idea of a pointer is that instead of creating a new variable in the memory, you are just going to ''point'' to one that is already stored there. This can have several uses, and in AGS even has some special ones.
To understand what a pointer is, we must first understand the more basic idea of variables. If you already understand variables, you can skip over this section.
 
===Variables===
A variable, in the context of scripting, is a way to represent a value. In AGS, there are five different [http://www.bigbluecup.com/manual/Datatypes.htm data types] which can be used to represent a variable. These types include '''char''', '''short''', '''int''', '''String'''<sup>1</sup>, and '''float'''<sup>2</sup>. A '''char'''-type variable is one that can hold only a single character (i.e., 'A', 'B', etc.) or a number within the range 0 to 255. A '''short'''-type variable can store integers within the range -32768 to 32767. An '''int'''-type variable can store integer values within the range -2147483648 to 2147483647. A '''String'''-type variable can hold a string of characters (i.e., "this is some text!") of ''virtually'' infinite length. A '''float'''-type variable can store floating-point decimals within the range -2147483648.0 to 2147483647.0, and has precision up to approximately 6 decimal places, though this will vary based on the actual number.
 
For information on defining and assigning values to variables read the entry in the manual [http://www.bigbluecup.com/manual/Datatypes.htm here].
 
'''<sup>1</sup>The String type is only defined as of AGS v2.71 and higher. Older versions use the now deprecated string type.'''
 
'''<sup>2</sup>Floating-point decimals won't always evaluate as you might expect when doing certain mathematical operations (this is due to their precision levels). See the manual entry on [http://www.bigbluecup.com/manual/Datatypes.htm data types] for more information.'''
 
===Pointers===
Okay, so now that we understand what a variable is, we can begin to understand what a pointer does. The basic idea of a pointer is that instead of creating a ''new'' variable, we are simply going to ''point'' to a variable that is already stored in the memory. This can have several uses in scripting, and AGS even has some special ones.


==Defining A Pointer==
==Defining A Pointer==
''And, how do I use them?''
''And, how do I use them?''


In AGS, you can only create pointers to certain types of variables. These are called ''managed'' types.
In AGS, you can only create pointers to certain data types. These are called the ''managed'' types.


===Managed Types===
===Managed Types===
Line 19: Line 31:


===Working With Managed Types===
===Working With Managed Types===
However, you can work with these managed types through pointers.  You define a pointer by typing the variable type, then a space, an asterik (*), and finally the name of the pointer. So, to create a pointer named GUIPointer to point to the GUI object named gMygui, you could type:
You can work with these managed types through pointers.  You define a pointer by typing the name of the managed data type, then a space, an asterik (*)<sup>3</sup>, and finally the name of the pointer. So, if we want to create a GUI pointer (this is expressed as GUI*) called GUIPointer, we could type the following:


   GUI *GUIPointer = gMygui;
   GUI *GUIPointer;
 
This creates a pointer that can ''point'' to any GUI stored in the memory. However, until it is assigned a value, it is an empty, or ''null'' pointer. We'll first discuss how to assign pointers a value, then we'll discuss null pointers.


'''''Note that if the pointer is global (outside of all functions), then you cannot assign it an initial value.'''''
===Assigning A Pointer A Value===


'''''Also note that if you are defining multiple pointers at once, you have to place an asterik before the name of each pointer.'''''
To make it point to a GUI, you assign it the value of the GUI you want it to point to (with the assignment operator, '='). So to make GUIPointer point at the GUI named MYGUI, you would type:


'''''Furthermore, you should take note that the asterik can actually be placed beside the variable type (i.e., GUI* GUIPointer instead of GUI *GUIPointer), but it will always be parsed as being attached to the variable (i.e., GUI *GUIPointer).'''''
  GUIPointer = gMygui;


====A More Useful Assignment====
As long as the pointer isn't global (i.e., the pointer is defined inside of a function), then you can also assign it an inital value when you create it, like this:
Of course this would be a rather pointless assignment, unless you just wanted a new alias for your GUI.  A more useful assignment makes use of the function GUI.GetAtScreenXY:


   GUI *GUIUnderMouse = GUI.GetAtScreenXY(mouse.x, mouse.y);
   GUI *GUIPointer = gMygui;


As implied by the name of the pointer, this pointer will point to the GUI that the mouse is over.  This brings to point an interesting question though. What if there is no GUI under the mouse?  Well, in that case, GUIUnderMouse would be set to ''null'', which means that it isn't pointing to anything.
Global pointers can't have an initial value assigned though, so this will only work if you define the pointer inside of a function. When defining more than one pointer of the same type at once, it is necessary to use an asterik for every pointer. So, if you want MyGUIPointer to point to MYGUI, and OtherGUIPointer to point to OTHERGUI, you can do this:


==Null Pointers==
  GUI *MyGUIPOINTER = gMygui, *OtherGUIPointer = gOthergui;
If a pointer is null, then basically all you can do with the pointer is make it point to something (assign it a value as in the examples), and test it against other pointers (or variables) of the same type. You can test to see if a variable is null with the '==' operator.


Suppose, for example, we have a GUI pointer (GUI*) called GUIUnderMouse which we will use to point to the GUI under the mouse. We can check if there is a GUI under the mouse (after assignment) with the following line:
If you forget an asterik then it will try to create a new instance (create a new variable) of the type GUI. AGS doesn't allow the user to create new instances of managed types, so this would crash your game. So, it's always important to remember your asteriks.


  GUI* GUIUnderMouse = GUI.GetAtScreenXY(mouse.x, mouse.y) // assignment
'''<sup>3</sup>The asterik doesn't necessarily have to be attached to the name of the pointer, such as "GUI *MyGUIPointer", it can also be attached to the data type itself, such as "GUI* MyGUIPointer". However, it will still be compiled as if it is attached to the name of the pointer, not the data type, so if you define multiple pointers at once, you will still need an asterik for each pointer.'''
  if (GUIUnderMouse == null) {} // no GUI under mouse


You can also test if a pointer is ''not'' equal to null with the '!=' operator:
===A More Useful Assignment===
This type of assignment is rather pointless however, unless you just want a new alias for your GUIs. A more useful assignment makes use of the function GUI.GetAtScreenXY. This function returns a GUI* to the GUI at the specifed coordinates. So, if you wanted to see what GUI the mouse was over, you could do this:


   if (GUIUnderMouse != null) {} // there is a GUI under the mouse
   GUI *GUIUnderMouse = GUI.GetAtScreenXY(mouse.x, mouse.y);


==Comparing Pointers==
===Testing A Pointer's Value===
We've seen how to assign values to pointers, and how to test whether or not they are null, so let's take a look at comparing them to other pointers and variables of the same type:
If you want to see what a pointer is actually pointing to, you can use the boolean operators == (checks equivalency) and != (checks inequality). So, to see if GUIUnderMouse is MYGUI or not, you could do this:


  GUI *GUIUnderMouse = GUI.GetAtScreenXY(mouse.x, mouse.y);
   if (GUIUnderMouse == gMygui)
   if (GUIUnderMouse == gMygui) {
     Display("MYGUI is under the mouse!");
     Display("MYGUI is under the mouse!");
    }
   else if (GUIUnderMouse != gMygui)
   else if (GUIUnderMouse != gMygui) {
     Display("MYGUI is not under the mouse!");
     Display("MYGUI is not under the mouse!");
    }


First we assign the pointer to hold the value of the GUI under the mouse as we did before. Then we test if the GUI is MYGUI with the statement "if (GUIUnderMouse == gMygui)".  If the GUI under the mouse was gMygui, then they will be equal, and the statement will pass as true and the statement will be displayed (avoid doing this repeatedly or else it could be a hassle to return back to the game).
===Null Pointers===
If a pointer isn't pointing to anything, it is known as a null pointer. It will actually hold the value '''null''' (which is equivalent to 0). Operations on null pointers will cause the game to crash, so you should always be sure that your pointer is non-null before using it.
 
You check if a pointer is null or not the same way you would normally check a pointer's value:
 
if (GUIPointer == null) { /* the pointer is null */ }
else { /* the pointer is non-null */ }


==What Pointers ''Do''==
==What Pointers ''Do''==
''Okay, so we can create, assign, and test pointers, but what do they DO?''
''Okay, so we can create, assign, and test pointers, but what do they '''do'''?''


Well, we've already discussed that they point to variables stored in the memory, but it's an interesting question as to how this can be useful. Pointers can provide major advantages over systems which lack them, in several areas:
Well, we've already discussed that they point to variables stored in the memory, but it's an interesting question as to how this can be useful. Pointers can provide major advantages over systems which lack them, in several areas:
Retrieved from ‘https://www.adventuregamestudio.co.uk/wiki/AGS_Pointers_for_Dummies’