Add.to.pic

The add.to.pic command allows you to add a view to the visual picture screen in memory.

Syntax

add.to.pic(byt VIEW, byt LOOP, byt CEL, byt X, byt Y, byt PRI, byt MGN);

Remarks

Cel CEL of loop LOOP of view VIEW is drawn on the picture at X, Y with a priority of PRI. The priority argument can be used to add views behind other parts of the picture.

The location is validated by AGI to ensure the view is not added so that any part of it is off the screen. It does this by using the shuffling method for screen object placement, but ignores other objects and the horizon.

If PRI is zero, the priority is set automatically according to the view's Y value. Use a PRI value of 3 through 15 to force the priority to a specific value. If the PRI value is 1 or 2, the view won't show on the visual screen but the view's control line box (if MGN argument is 0, 1, 2, or 3) will still be drawn.

Use the MGN property if you want the added view to include a control box. If MGN is 0, 1, 2 or 3, AGI draws a box on the priority screen. The box is drawn so the bottom line is on the view's bottom row, and the top line is on the last row that has the same priority. So if you add a view with a Y position at the bottom of a priority band you'll get a taller box than if you add it near the top of a band. If you position it on the top row of a priority band, you'll get a line instead of a box.

Unless the view resource is needed for something else, you should discard it after adding it to the picture, in order to limit memory usage. AGI adds a script entry to the script stack each time add.to.pic is executed.

Possible Errors

If the LOOP value does not point to a valid loop, AGI raises trappable error #6.

Try to make sure you limit your values for PRI and MGN arguments to less then or equal to 15. If you don't, you may get unexpected results; AGI uses the following formula for calculating the actual values for PRI and MGN based on the passed argument values:
PRI(actual) = PRI(argument) AND 0x0F
MGN(actual) = PRI(argument)>>4 OR (MGN(argument) AND 0x0F)

Do not use cels with widths less than three pixels if you want to draw a control box; AGI's algorithm to draw the control box has a bug in it that draws a line across the entire screen if width is 1 or crashes the game if width is 2.

The view must be loaded before you use it with add.to.pic or AGI will raise trappable error #3. Use the load.view command to load a view.

Example

Code:

load.view(9); [ ensure view is loaded
add.to.pic(9, 0, 0, 20, 120, 14, 2);
[   first cel of first loop of view 9
[   is added to current picture at position (20, 120)
[   with priority 14, and an alarm line (MARGIN = 2)
[   is drawn along bottom row of the cel on the priority screen

discard.view(9);  [ discard view after adding it

Technical Information

Required Interpreter Version:	Available in all AGI versions.
Byte-Code Value:	122 (0x7A hex)

See Also

Screen Objects/View Commands
add.to.pic.v