Graphics System

hBasic Manual

Graphics System changes

Coordinates Upgrade	Upgraded positioning system
Display List	Changes to the display list

Object Motion	Added motion for objects.

Sprites and Animation	Added the Sprite graphics object
Graphics Parameters	New parameters for objects.
Updated Object Table	graphics objects parameter list.

Other ( Graphics command changes ) ( Graphics functions )

Coordinates Upgrade

The graphics coordinates system was upgraded from integers to single precision 32 bit floating point, inline with the Android graphics library.
Even though screens will not use sub-pixel values, the fractional part is necessary for internal motion calculations.

If you are using the built-in motion vectors, then you may get fractional parts back from x,y values, since they represent the true distance moved.

Legacy Basic programs should not see any difference, as they don't use hBasic motion commands at all.

Display List

Additional commands were added to manage the display list without having to resort to GR.GETDL and GR.NEWDL.

Display List Z-Ordering

Objects that are put on a display list for rendering have a z-index.
(The z-index is not the same as the object number).

The z-index is the same as the display list position and determines the depth position of objects.

The first display list item will be rendered first, i.e the 'back' of the screen.
z index is lowest.

The last display list item will be rendered last. i.e the 'front' of the screen.
z index is highest.

Groups

Group objects are no longer added to the display list upon creation. (since v5.00)
Group objects need to be on the object list but don't serve any purpose on the display list.
Therefore they are no longer added to the display list for the GR.GROUP.. commands.

If you try to move a group object in the display list (z-ordering) via GR.DL.MOVE, only the objects in their lists will be moved. However, GR.DL.REMOVE will remove group objects (if they are on the display list), along with the objects in their lists.

Object Motion

All viewable objects now have "speed" and "dir" properties via GR.GET.VALUE or GR.MODIFY parameters.
These are properties for a velocity vector of motion. It allows an object to move upon GR.MOTION.

GR.MOTION and object properties

In general, when GR.MOTION is called, it updates the positions on all objects in the display list.
For more advanced usage see GR.MOTION and motion with tweens.

An object is moved relative to the previous GR.MOTION or GR.MOTION.MARK time, whichever was called before.
If both had not been called before, the reference time is the start of the graphics screen.

The object is moved according to it's speed and direction parameters;

Speed ("speed")

This is given as pixels per second.

If the speed is zero, the object will not move.

If the speed is non-zero and positive, the object will move.
If the speed is negative, the object will move oposite to it's direction ("dir").

In physics, a speed cannot be negative but it is allowed here for convenience.

The default speed for all objects is zero (no movement).

You may express the speed with a fractional part for accuracy.

To stop an object (no movement), set the speed to zero (default).

Direction ("dir")

This is given as an angle in degrees.
The default direction for all objects is zero, which is pointing to the right (east).
Direction angles move clockwise, so 90 degrees is pointing down (south).

You may express the direction with a fractional part for accuracy.

Manual Movement

If you never use GR.MOTION (e.g legacy programs), then objects will not be moved by it.

If you don't want objects affected by GR.MOTION, set their speeds to zero.
You can still manually move them in the usual way by using GR.MODIFY.

e.g
GR.MODIFY object, "speed",0                % will not be moved by GR.MOTION
GR.MOTION                                               % for other objects and animation
GR.RENDER

e.g                                                                % manual positioning
GR.MODIFY object, "x",x, "y",y              % (see whole object positioning)

GR.MOTION does not move objects with zero "speed" nor animate sprites with zero "arate".

Tweens

Tweens are explained under Motion and Tweens.

Sprites and Animation

The Sprite object has been added to the graphics engine.
A Sprite is similar to a bitmap but with the added feature of Animation.

(See also, Sprites and Animation commands)

Sprite Properties

As well as the general purpose properties (including speed and dir) sprite objects also have the following parameters.

for GR.GET.VALUE

"bitmap" , "anim" , "arate" , "aframe" , "aloop" , "width" and "height"

and for GR.MODIFY,

"bitmap" , "anim" , "arate" , "aframe" , "aloop"

where

Parameter property	Description	default	special remarks
bitmap	Standing bitmap pointer	*	used if no animation
anim	Animation Index pointer	0	0 = no animation
arate	Animation Rate	10	frames per second 0 = freeze frame <0 = reverse animation
aframe	Current animation frame	0	0 to max (zero based)
aloop	Animation Looping or not	1	0 = no looping
width	width of standing bitmap	*	read-only
height	height of standing bitmap	*	read-only

(* filled upon creation)

Standing bitmap

Before you create a sprite, you must have at least a bitmap. This is the called the 'standing' bitmap.
GR.BITMAP.LOAD bmp, "h-stand.png"

To create a Sprite with no animation,
GR.SPRITE.DRAW s0, 100, 100, bmp % spr_obj, x , y , bitmap_ptr

This creates a sprite object on the object list and also adds it onto the display list.
The standing bitmap bmp is used when a sprite is not animating (anim=0).

Changing a standing bitmap

The standing bitmap can be changed with parameter "bitmap", which is a bitmap index.
GR.MODIFY s1, "bitmap", bmp2 % bitmap bmp2 must already exist

Animation

An animation is a sequence of bitmaps. Similar to bitmaps, there is an internal list of Animations.
This list is indexed the same way as bitmaps, it starts with 1 and grows as more animations are added.
When you create an animation, you get back an animation index (pointer).
You can attach this animation to a sprite using this index.
Animations are not graphic objects, similar to bitmaps, they are attached to sprites.

To create a new Animation, you can load it from a file
e.g GR.ANIM.LOAD ani, "h-animate.png",32,33,16

See GR.ANIM.LOAD for more information.

Animations may be created before or after sprite object creation.

Animation to new Sprite

To create a new sprite with animation,
First create and load an animation.
GR.ANIM.LOAD ani,"h-animate.png",32,33,16

Then create the new Sprite and attach the animation;
GR.SPRITE.DRAW s1,100,100,bmp,ani % obj, x , y , bitmap, animation

Note that you still need to specify the standing bitmap.

The default animation rate for a new sprite is 10 frames per second (fps) and will animate with each GR.MOTION.
The animation is based on times between each motion (see below).

Animation to existing Sprite

To attach or change an Animation to an existing Sprite, use GR.MODIFY

GR.MODIFY s0, "anim", ani
where s0 is the sprite object number and ani is the animation index (pointer).
The animation must already exist. The exception is 0 = no animation.

To stop animating, remove the animation by setting the sprite's animation pointer to zero.
GR.MODIFY s1, "anim", 0
This means the sprite has no animation and defaults to it's standing bitmap.
Alternatively, you can freeze the frame by setting the animation rate "arate" to zero (see bleow).

Movement and Animation Rates

As with all objects, you can use the built-in motion vectors to move the sprite with GR.MOTION
or you can manually set the position of a sprite with GR.MODIFY s1, "x", X, "y", Y
(see the section on Object Motion).

If you opt to move sprites manually, set their speed to zero to avoid being moved by GR.MOTION.

In addition to movement, GR.MOTION also updates a sprite's animation according to it's animation rate ("arate"), see GR.MOTION for the effects of entering a motion loop. Therefore, if you are using animation or tweens, you must also use GR.MOTION.

The animation rate arate is given as frames per second. The default for a new sprite is 10.

Zero aRate

If a sprite has animation (anim non-zero) but the arate is zero, then the frame is not updated, it stays on the current frame i.e freeze frame. It does not revert to it's standing bitmap because there is still a valid animation (anim non-zero).
If you are manually changing the current frame (aframe), or if you are using a Tween, then you should set the aRate to zero (so that arate does not interefere with you manual rate).

Negative aRate

If a sprite has animation (anim non-zero) but the arate is negative, the animation is reversed (frames played backwards) at the negative rate.

Graphics Parameters

General Purpose (common)

Four more parameters have been added to the General Purpose parameters (Paint and Alpha),
these are "x","y","speed" and "dir".

These parameters are available to all display list objects (updated object table).

General Purpose Parameters
Type	Position	Position	Paint	Alpha	Motion	Motion

Name (string)	x	y	paint	alpha	speed	dir

Note that as before (legacy Basic), the alpha is that of the object (not the paint's alpha). If the object's alpha has been changed, it overrides the paint's alpha.

Whole Object Positioning ( x, y )

"x" and "y" are for moving whole objects.

The position parameters are the same parameters for those objects that already have "x" and "y".
For other, objects that did not have them, "x" and "y" gives a position and will get the same values found for "x1", "y1" and "left","top".
e.g
GR.GET.VALUE oLine, "x",myvar % gets the same value as "x1"
GR.GET.VALUE oRect, "x",myvar % gets the same value as "left"

The difference being that if you modify "x" or "y" using GR.MODIFY, then the whole object is moved to that position (not just one corner).

e.g
GR.MODIFY oRect, "x", 200
Above command modifies both "left" and "right" values of the rectangle so that "left" is at 200 and "right" moves to right to preserve the same width. Similarly with "y" and "top","bottom".

Groups
If you GR.MODIFY the "x" or "y" of a group, the objects in it's list are also modified (moved to that position).
If instead, you want to move a group (and it's objects) relatively from their position, consider using GR.MOVE.

Motion Vectors ( speed, dir )

"speed" and "dir" are quantites for a vector of motion. Vectors allow an object to move in a specified way. This is described in the section on Object Motion.

Updated Object Table

Updated Graphics Object Table
Type	Pos	Pos	Pos	Pos	Other	Paint	Alpha	Motion	Motion
( common )	x	y				paint	alpha	speed	dir
arc	left x	top y	right	bottom	start_angle sweep_angle fill_mode	paint	alpha	speed	dir
bitmap	x	y			bitmap width (read-only) height (read-only)	paint	alpha	speed	dir
circle	x	y			radius	paint	alpha	speed	dir
line	x1 x	y1 y	x2	y2		paint	alpha	speed	dir
oval	left x	top y	right	bottom		paint	alpha	speed	dir
set.pixels	x	y				paint	alpha	speed	dir
point	x	y				paint	alpha	speed	dir
poly	x	y			list	paint	alpha	speed	dir
rect	left x	top y	right	bottom		paint	alpha	speed	dir
sprite	x	y			bitmap anim arate aframe aloop width (read-only) height (read-only)	paint	alpha	speed	dir
text	x	y			text	paint	alpha	speed	dir
clip.start	left x	top y	right	bottom	RO	paint	alpha	speed	dir
rotate.start	x	y			angle	paint	alpha	speed	dir
group	x	y			list	paint	alpha	speed	dir

x,y is used for whole object positioning

( common ) means General Purpose.
(read-only) will error if used with GR.MODIFY