AGIWiki/add.to.pic

The add.to.pic command draws a cel from a view to the visual picture screen in memory. There is an indirect version of this command called add.to.pic.v.

Syntax

add.to.pic(byt viewNumber, byt loopNumber, byt celNumber, byt x, byt y, byt priority, byt margin);

Remarks

Cel celNumber of loop loopNumber of view viewNumber is drawn on the picture at position (x, y) with a priority of priority. If margin is 0, 1, 2, or 3, the base line of the object (the bottom row of pixels of the cel) is given a priority of margin. Since priority is taken into account, you can use add.to.pic to add cels behind other parts of the picture.

The location is validated 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 object placement, but uses flags to ignore other objects and the horizon.

If priority is zero, the priority is set automatically according to the view's y position. Use a value of 4 through 15 to force the priority. Using a value of 1,2, or 3 for priority is technically allowed, but the view won't show on the visual screen no matter what. The view's control line box (if margin argument is 0, 1, 2, or 3) will still be drawn.

Use the margin property if you want the added view to include a control box. If margin 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.

Try to make sure you limit your values for priority and margin 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 priority and margin based on the passed argument values:

 priority(actual) = priority(argument) AND 0x0F
 margin(actual) = (priority(argument) AND 0xF0)>>4 OR (margin(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.

Note that the view must be loaded before you use it with add.to.pic.

Unless the view resource is needed for something else, you should discard it after adding it to the picture, as it is no longer needed by the interpreter.

Parameters

For add.to.pic

• viewNumber: a number, 0-255, specifying the view resource that contains the cel that should be drawn
• loopNumber: a number, 0-255, specifying the loop in the view resource that contains the cel that should be drawn
• celNumber: a number, 0-255, specifying the cel that should be drawn
• x: a number, 0-255, specifying the x position where the cel should be drawn
• y: a number, 0-255, specifying the y position where the cel should be drawn
• priority: a number, 0-15, specifying the priority that should be assigned to the cel when it is drawn; note: after the cel is drawn, the priority cannot be changed
• margin: a number, 0-3, specifying the priority of the base line of the object (the bottom row of pixels of the cel); this parameter can be used, for example, to prevent ego from walking through the cel, making it appear to be a solid object on the screen

For add.to.pic.v

• viewNumber: a variable, v0-v255, whose value specifies the view resource that contains the cel that should be drawn
• loopNumber: a variable, v0-v255, whose value specifies the loop in the view resource that contains the cel that should be drawn
• celNumber: a variable, v0-v255, whose value specifies the cel that should be drawn
• x: a variable, v0-v255, whose value specifies the x position where the cel should be drawn
• y: a variable, v0-v255, whose value specifies the y position where the cel should be drawn
• priority: a variable, v0-v255, whose value specifies the priority that should be assigned to the cel when it is drawn; note: after the cel is drawn, the priority cannot be chagned
• margin: a variable, v0-v255, whose value specifies the priority of the base line of the obejct (the bottom row of pixels of the cel); this parameter can be used, for example, to prevent ego from walking through the cel, making it appear to be a solid object on the screen

Possible errors

• if the specified view has not yet been loaded (see load.view), then the game will crash with a view not loaded error
• every time the add.to.pic or add.to.pic.v command is issued, it adds to the script buffer; this can lead to a script buffer overflow error
  • This issue can be overcome by blocking interpreter writing to the script buffer with flag 7.

Example

The following example uses add.to.pic to draw cel 3 from loop 2 of view 15 at position (40, 120) with a priority of 9 and a margin of 0 (unconditional barrier).

<syntax type = "C++">

load.view(15);
add.to.pic(15, 2, 3, 40, 120, 9, 0);

</syntax>

The next example uses the indirect command add.to.pic.v to accomplish the same thing:

<syntax type = "C++">

load.view(15);

v200 = 15;
v201 = 2;
v202 = 3;
v203 = 40;
v204 = 120;
v210 = 9;
v215 = 0;

add.to.pic.v(v200, v201, v202, v203, v204, v210, v215);

</syntax>

Avoiding problems with script buffer and memory while restoring the original room without new.room:

<syntax type = "C++"> if (cutscene_block) {

 set(f7); 
 load.view(cutscene_view);
 add.to.pic(cutscene_view, 0, 0, 0, 0, 0, 0);
 discard.view(cutscene_view);
 reset(f7);
 
 // code, possibly print, timer and/or waiting for player input
 
 set(f7);
 load.pic(v0);
 draw.pic(v0);
 discard.pic(v0);  
 show.pic(v0);
 reset(f7);

} </syntax>

Technical Information

Required interpreter version	Available in all AGI versions
Bytecode value	122 (0x7A hex)

Sources

Some of the content of this page was taken from the AGI Studio & WinAGI help files.