George

From TVPaintWiki
Jump to: navigation, search

<<<Main Page



The autopilot of an aircraft is sometimes referred to as "George."


Meet George

George is a macro scripting language that can be used to control TVPaint. It is an "automatic pilot" that sends instructions such as "select this function", "use this color", "draw this", etc. . to TVPaint. Each instruction corresponds to an TVPaint function or icon. Everything takes place as though George was clicking the icon in the interface for you. Rather than clicking ten or twenty times on the same button yourself, simply ask George to do it for you.

You can simply use existing programs (i.e., scripts) or you can create your own. With George, you can create an infinite number of custom drawing functions and automate the use of TVPaint. Many example scripts are included with TVPaint and are stored in the George subdirectory.

George programs are basically plain ASCII text files. You can use any text editing program to create and edit them.

Suppose that you wanted to draw a glass ball. To do this, you would need to cutout a custom brush (for the reflective surface), set the parameters to apply this brush in a circle, draw filled circle (which will be filled with the brush), adjust opacity mapping parameters to obtain a reflection, select white and redraw the circle.

If you only had to do one of these balls, you could execute the operations manually. However, what if you needed 10 or 20 glass balls. It would likely get pretty tedious - this is where George comes in. With the proper program, all you have to do is to draw a circle to define the contours of the ball and George will do the rest for you.



Launching modes

Each George program uses a launching mode indicated by a small icon adjacent to the corresponding line on the George panel. Essentially, this indicates drawing actions from which script derives information :

One mode

You don't need to draw anything before using this type of George program. The program does not receive any parameters.

Single mode

You will need to draw a dot in a frame to run the program, which will receive a character string containing the word "Single", a pair of coordinates (x,y) and a code identifying which mouse button you pressed (0 for left, 1 for right). Each parameter in the string is separated from the previous parameter by a space.

Freehand mode

You will need to draw a freehand line in the frame to run the program. Each time you move the mouse, the program will receive a character string containing the word "Freehand", a pair of coordinates (x,y) and the code identifying which button you pressed. Each parameter in this string is separated from the previous parameter by a space. The program can store the coordinates it receives them, and for example may execute when it detects that the button is released.

Line mode

You will need to draw a straight line in the frame to run the program. The program will receive a character string containing the word "Line", two pairs of x and y coordinates (the start and end of the straight line) and the code for the button that was pressed. Each parameter in this string is separated from the previous parameter by a space.

Rectangle mode

You will need to draw a rectangle in the frame to run the program. The program will receive a character string containing the word "Rectangle", two pairs of x and y coordinates (the opposite corners of the rectangle) and the code for the button that was pressed. Each parameter in this string is separated from the previous parameter by a space.

Circle mode

You will need to draw a circle in the frame to run the program. The program will receive a character string containing the word "Circle", a pair of x and y coordinates (the center of the circle) and the code for the button that was pressed. Each parameter in this string is separated from the previous parameter by a space.

George language

George is a very rich programming language and even borrows many features from higher level programming languages like C, including loops, conditional tests and calculations.

Language conventions

Variables

Numeric and characters string variables are managed transparently? You don't need to declare variable types before using. Thus you can write :

	a = 3
	MyVariable = "Monday"

Additionally, variable names are not case sensitive. Thus, PRINT, Print, PRint, PriNt would all be interpreted the same.

Reserved variables

Some variable names are reserved for George. These variable names may be modified at any time without warning. You can read these variables to see what they contain, but it is strongly recommended that you do not write into them. An example is the George Result variable that is used in particular to store the results of TVPaint commands.

Program line

You can only include one instruction on any one line. For example, the following is an example of what you cannot write :

	PRINT "Hello" PRINT "see you tomorrow ..."

Like variable names, instruction and command names are not case sensitive. Thus , "Tv_AliasOn", "Tv_aliason", "TV_aliasON" would all be interpreted the same.

George instructions

For better readability, George instructions lines can start with "#" character. Thus you can write :

	#PRINT "Hello"

instead of :

	PRINT hello

Do not confuse lines to be used by George (which start with the # character) and TVPaint command lines (which all start with tv_). Lines to be used by George from program structure (loops, tests, calculations, ...), whereas lines that contain TVPaint commands affect TVPaint panels and screens.

Remarks

Two slashes will "remark out" whatever follows. This allows you to add comments to your code :

	//PRINT "hello" 	will not write anything
	PRINT "hello" 		//actually writes hello

Arithmetic operators

	- 	negative
	** 	exponent
	* 	multiplication
	/ 	division
	+ 	addition
	- 	substraction

Relational operators

	== 	equal to
	!= 	not equal to
	> 	greater than
	>= 	greater than or equal to
	< 	less than
	<= 	less than or equal to

Do not confuse the assignment operator = and the comparison operator ==. The former is used to assign a new value to a variable (like a = a +1 ) whereas the second is used to compare two expressions (like a == b) during tests. You MUST use the CMP instruction to find out if two character strings are identical. Do not use the equality operator ==.

Logical operators

	&& 	and
	|| 	or

Character strings and tables of variable

Character strings

All character (text) strings must be written between quotes (") or between single quotes ('). When you want to use either of these tow quote characters in a string, you must use the other quote character to surround it (for example, " It's finished ! " or ' the program name is "TVPaint" '). You can process numeric values like string values in operations like concatenation (joining several strings together). For example :

	PRINT "the result is " value

Use CONCAT instruction or the empty character string ("") if you want to concatenate two strings, in other words join them together one behind the other. The following two lines :

	CONCAT(string1, string2)

and

	string1""string2

produce the same result. If you want to concatenate these two strings and separate them by a space, you can write :

	string1" "string2

If you want to increment the numeric part of a character string (for example a file name) you can write :

	FOR i = 1 TO 10
	 	name = base""i		// base is the base name
	 	PRINT name
	END

Arrays

You can create variable arrays in George in the form var[i] or var(i), where i is a numeric value indicating the position of the required George in the table, and "var" is the generic name of the variables in the array. There is no need to make a prior declaration for the dimension (the number of Georges) in these tables because they are created dynamically. These arrays contain several dimensions (for example var[i,j] or var(i,j) for a table with two dimensions). Example :

	day[1] = "Monday"
	day[2] = "Tuesday"
	day[3] = "Wednesday"
	For i = 1 TO 3
	 	PRINT day[i]		// Displays "Monday", "Tuesday", "Wednesday"
	END

Procedures

A procedure is an independent part of a program that is called from the main program and that carries out some processing on the data in the program. A procedure can repeat a set of operations without the need for you to duplicate the corresponding lines in the program. Simply create a procedure, and then call it from the main program. Procedures are recursive, so a procedure can call itself. All procedures MUST be placed after the end of the main program, although, their order is not particularly important. You can use any George instructions and any TVPaint commands in a procedure.

Procedure declaration and call

Use the FUNCTION instruction to declare a procedure. You must state the name of the procedure and the names of the variables transferred to the procedure, after the FUNCTION instruction. The procedure must end with an END instruction. Therefore the general form of a procedure is :

	FUNCTION name(var1, var2, ..., varN)
	 	(instructions in the procedure)
	END

The procedure can access any of the variables declared in the main program at the time that the procedure is called. The main program will recognize any new variable declared in the procedure, after returning from the procedure. You can also create variables that will only be recognized in the procedure, by using the LOCAL instruction. Use the RETURN instruction to return a value to the main program. Procedure "name" is called from the main program as follows :

	name(var1, var2, ..., varN)

The number of variables transferred must be exactly the same as the number of variables expected by the procedure. If the procedure returns a result, you can store it in a variable, or test it, etc...

Procedure instructions
FUNCTION

Syntax :

	FUNCTION Dothis(var1, var2, ..., varN) 
	 	(instructions in the procedure)
	END

Declare a procedure named Dothis, which expects variables var1, var2, ...., varN. Note that var1, var2, ..., varN are the names by which the received variables are known in the procedure. Examples :

	 FUNCTION Counter(number)
	 	LOCAL i
	 	IF (i > 0)
	 	 	FOR i = number TO 0 STEP -1
	 	 	END
	 	 	RETURN "Countdown finished"
	 	ELSE		
	 	 	RETURN "Countdown impossible"
	 	END
	END

Example calls to this procedure from the main program :

	PRINT Counter(100)

or

	var = 100
	a = Counter(var)
	PRINT a        
RETURN

Syntax :

	RETURN expression

Returns the value expression to the main program. This instructions is not compulsory in a procedure. Examples :

	RETURN 0
	RETURN "End of procedure"
	RETURN var
LOCAL

Syntax :

	LOCAL var1 var2 varN

Declares one or several local variables in the procedure. These variables are only available (in other words recognized) within procedure. Example :

	LOCAL day1 day2
INCLUDE

Syntax :

	#INCLUDE "file"

Declares a file to be inserted in the current George script. Example :

	#INCLUDE "include/basic.grg"

When George command interpreter meets a line containing this command, it replaces it by the contents of the specified file. This allows you to create function libraries and include them in your George script. To access the specified file, George gives priority to tow search directories :

  • The TVPaint home directory (mentioned in the HomeDir line in the TVPaint.ini file)
  • The directory containing the George script in which the INCLUDE instruction was given.

From these base directories you can specify an access path for the file to be included (for example, #INCLUDE "library\strfunc\strlib.grg"). If the file to be included contains procedures, you must place the INCLUDE line after the end of the main program. You will find two examples of function libraries for the processing of character strings ("basic.grg" and "Advanced.grg") in the "George\Include" directory of TVPaint.


You can only inlude 1 text file in your script that contains Procedures. If you want to include two file you have to either collect them to one. or to include the second file in you first file. this Include command should be in the top of you first file before the other procedures. this example should work. All 3 files should be saved in the same directory.

Main Script

PARAM none
sayHelloBasic()
sayHelloAdvanced()
#INCLUDE "basic.grg"

INCLUDE SCRIPT basic.grg

#INCLUDE "advanced.grg"
FUNCTION sayHelloBasic()
	tv_warn "Hello World Basic"
END

INCLUDE SCRIPT advanced.grg

FUNCTION sayHelloAdvanced()
	tv_warn "Hello World Advanced"
END