hBasic Manual

Gets the width and height of the VIew Size instead of the device size.

The width and height returned from GR.SCREEN has been modified to always return
the current canvas size (the draw view). This is the area in which you can draw.

This size may change if you hide or show either the status, navigation or action bars.

density_DP is the density as pixels per inch .eg 160 on a 160 dpi display.

density_SP is the density as scaled pixels per inch.

GR.SETACC level_nexp            % default is 2

GR.TOUCH touched_lvar , x_nvar, y_nvar {,  unscale_lexp }    % first touch
GR.TOUCH2 touched_lvar , x_nvar, y_nvar {,  unscale_lexp }   % second touch

touched returns true if the screen was touched.
If the screen was touched, x,y are the returned touch coordinates. By default, these are actual device coordinates.

An optional unscale flag was added and is by default false if ommited.
If unscale is given and is true (non-zero), the actual x,y coordinates are unscaled according to the current screen scale (set by GR.SCALE). This will give you back coordinates in the range of your development size.

GR.BOUNDED.TOUCH touched_lvar , left_nexp, top_nexp, right_nexp, bottom_nexp {, scale_lexp }
GR.BOUNDED.TOUCH2 touched_lvar , left_nexp, top_nexp, right_nexp, bottom_nexp {, scale_lexp }

touched returns true if the screen was touched within the bounds of the rectangle left, right, top, bottom.
By default, the rectangle is expected as actual device coordinates.

An optional scale flag was added and is by default false if ommited.
If scale is given and is true, the rectangle coordinates are scaled the same as the current screen scale (set by GR.SCALE). This will test the rectangle according to your development range.

Note that the rectangle is treated with right,bottom as exclusive (not part of the rectangle).

GR.BITMAP.CLR bitmap_ptr_nexp {, paint_nexp}

Fills a bitmap with transparency without destroying it.
Anything already on the bitmap is cleared. There is no alpha blending.
An optional paint object can be supplied for a fill otherwise it will be transparent.

GR.BITMAP.BLOT bitmap_ptr_nexp , x_nexp , y_nexp, width_nexp, height_nexp {, paint_nexp}

Same as gr.bitmap.clr but fills a rectangle within the bitmap.

GR.BITMAP.SCAF bitmap_ptr_nvar , scale_nexp {, smooth_lexp}

Scale a bitmap by a scale factor in both directions with optional smoothing.

scale

smooth

GR.CLIP.START object_ptr_nexp, left_nexp, top_nexp, right_nexp, bottom_nexp{, 
RO_nexp}

GR.CLIP.END {object_ptr_nexp}

GR.CLIP.START replaces the legacy GR.CLIP

Google does not allow for a clip region to expand since Android Pie (API-28). Because of that
4 out of the original 6 Region Operators are not supported;

Region OP	Allowed
0 Intersect	yes
1 Difference	yes
2 Replace	no - runtime error
3 Reverse Difference	no - runtime error
4 Union	no - runtime error
5 XOR	no - runtime error

thus GR.CLIP.START only accepts 0 or 1 for the region code.

GR.CLIP.END restores the canvas to the state (and region size) before the last clip.
It is strongly advised to use GR.CLIP.END after your objects are clipped.
Previously this was achievable with Region Op 2, but since API 28, GR.CLIP.END is the only way to restore the canvas size.

object_ptr_nexp is the marker object returned of either the clip START object  or the (optional) clip END object. These are useful for display list manipulation ( similar to GR.ROTATE).

You may nest clips as long as each block is properly GR.CLIP.ENDed.

These commands use the same canvas stack as GR.ROTATE.{start / end}. You may nest both types but you cannot interwine CLIP STARTs with ROTATE ENDs (and vice versa).

i.e, Always match the correct END type with the last used START.
e.g GR.CLIP.START...  GR.ROTATE.START.... GR.CLIP.START... GR.CLIP.END...GR.ROTATE.END..  GR.CLIP.END

These are enhancements made to accept multiple input parameters instead of just one with the same command.

GR.SHOW object_number_nexp {,  ... }
 shows one or more objects.

GR.HIDE object_number_nexp {, ... }
hides one or more objects.

e.g

GR.GET.PARAMS object_ptr_nexp , param_array$[]

In addition, the general purpose parameters have been extended with "x","y","paint","alpha", "speed" and "dir" for all objects.

Read-Only Values

In hBasic, for GR.GET.VALUE and GR.MODIFY, all parameters are 'get'-able, but not all parameters are 'mod'-ifiable. An example would be the "width" value of a Sprite object which is read-only. The updated Object Table is found here.

GR.GET.VALUE object_ptr_nexp {, tag_sexp , value_nvar | svar } ...

There is no change to this command, except that all the newly added general purpose parameters are also available to get.

GR.MODIFY object_ptr_nexp | array[ ]  {, tag_sexp, value_nexp | sexp> } ...

Added Array option

Group Object behaviour
X,Y behaviour

Display List Ordering

See here for an explanation of display list ordering.

GR.DL.GETZ <index_nvar , object_ptr_nvar> {, ...}

Gets the z-index of an object object_ptr into index.
Returns a value of -1 if not on display list.

Note that this can potentially return position 0 even though the reserved object 0 cannot be moved.

Display List Moving

GR.DL.MOVE pos_nexp , < object_ptr_nexp | arr[]_array[] > {, ...}

GR.DL.MOVE will move the object(s) 'after' the z-index pos.

You can give multiple objects or arrays.
If it's an array, each object in the array is moved.
An object may also be a group object (see below).
The object(s) does not have to already be on the display list.

If an object does not exist (not in the object list), there will be an error.

Current objects will be shifted to the right to make room.
The first object will be moved 'after' pos, i.e (pos+1).

Each successive object is moved 'after' the last moved object.
The last object moved will be nearest the end of the display list (screen front).

Any holes left behind are filled by shifting objects from the right to the left.

Move to Back
To specify a move to position 1, set pos to 0. The object will be moved after position 0 and will render as the first item in the display list (back of screen).

To specify a move to the last position, set pos to a negative number. This will be rendered last in the display list (front of screen).

Special Moves
If the object is not on the display list, it will still be put on the display list (if it exists on the object list).
This is one way to move objects back onto the display.

If the object to move is a group object, the group object itself is not moved. But each object in it's list is moved in turn (even if the group object itself is not on the display list).
The last group item will be nearest the end of the list.    
Any group within a group is ignored.    
If any object does not exist (not in the object list), there will be an error.

Note that the object at index 0 is never shifted. This object is a reserved object and is never moved.

Display List Removing

An object not on the display list never gets rendered.
Removing an object from the display list does not remove it from the object list.

GR.DL.REMOVE < object_ptr_nexp | arr[]_array[] > {, ...}

See Sprites and Animation for an overview of these items.

A Sprite display list object is similar to a Bitmap display list object but with the addition of an optional animation.

As well as the general purpose properties (including speed and dir) sprites also offer the following
for GR.GET.VALUE
and for GR.MODIFY,
see Sprite Properties for more information.

GR.SPRITE.DRAW spr_nvar, x_nexp, y_nexp, bmpPtr_nexp {, animation_nexp}

Creates a Sprite object which is returned in spr and adds it to the display list.

A Sprite must have a bmpPtr called a Standing bitmap. This is displayed if the sprite has no animation.
The bmpPtr and it's bitmap must be created in advance.

The command can have an optional animation. If you use this parameter, you must create the animation in advance . If not, you can omit this parameter and attach an animation later.

By default a sprite's animation is 0 (no animation).

Example

See Sprites and Animation for an overview of these items.

Animations are not display list objects but can be attached to them.
Animations can only be attached to Sprites.

A sprite controls it's animation with it's  sprite properties;

GR.ANIM.LOAD ani_nvar, fileName_sexp, w_nexp, h_nexp, nFrames_nexp {, skip_nexp}

GR.ANIM.SCAF ani_nvar, scale_nexp {, smooth_nexp}

GR.ANIM.GETF ani_nexp, bmp_ptr_nexp, frame_nexp

GR.ANIM.PUTF ani_nexp, bmp_ptr_nexp, frame_nexp

GR.MOTION
GR.MOTION  < object_ptr_nexp | arr[]_array[] > {, ...}

Updates all viewable objects to new positions based on their speed and direction.
Updates all animations (for sprites) based on their animation rates.

Normally you would use the first form (without parameters) in which all objects are moved, even if they are not on the display list and even if they are hidden.
The second form is for advanced usage, where only selected objects are moved. You may specify individual objects or an array of objects in any order.

Objects that have zero speed will not be moved.
Sprites that have zero animation rates will not be animated.

An object movement is timed relative to the previous GR.MOTION or GR.MOTION.MARK time (explained here).
Animations are timed the same way as motion.

Movement an animation is immediate. It is the responsibility of the coder to display the first position and/or frame before entering a GR.MOTION loop.

The results are not displayed until the next GR.RENDER. This gives you an opportunity to do collision testing or to detect the end of an animation.

If there are long periods between GR.MOTIONs, the time gap will still be calculated and the object might be placed at a large distance ahead. If this is not desired, you can call GR.MOTION.MARK to reset the start reference for the next GR.MOTION. This will ensure that the next GR.MOTION does not move the object relative to the previous call.

Marks the current time from which the next gr.motion will position relative to this time. Otherwise each gr.motion positions an object relative to the last gr.motion time.

This command does not move objects.

You would need this command,

This command resets the calculation, so that the objects can continue where they left off for future GR.MOTIONs.

Without this command, each GR.MOTION bases motion on the previous GR.MOTION reference. By this time the objects may have moved a long distance.