Difference between revisions of "Discard.view"

From AGI Wiki
Jump to navigationJump to search
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
The '''discard.view''' command removes a [[View Resource|view resource]] from memory. There is an [[Indirect Command|indirect]] version of this command called '''discard.view.v'''.
+
The '''discard.view''' command unloads a [[view]] resource from the [[memory heap]].
  
<code>discard.view(viewNumber);</code>
+
== Syntax ==
  
View <code>viewNumber</code> is discarded from memory.
+
discard.view([[number|byt]] A);
  
== Parameters ==
+
== Remarks ==
  
=== For discard.view ===
+
This command takes a number as the argument. [[View]] '''A''' is unloaded from [[memory heap|memory]].
  
* <code>viewNumber</code>: a number, 0-255, specifying which view resource to remove from memory
+
The '''[[discard.view.v]]''' command also unloads views, but takes a [[variable]] as the argument.
  
=== For discard.view.v ===
+
AGI adds a script entry to the [[script stack]] each time a view resource is unloaded.
  
* <code>viewNumber</code>: a [[Variable|variable]], v0-v255, whose value specifies which view resource to remove from memory
+
== Possible Errors ==
  
== Possible errors ==
+
Before unloading a [[view]], make certain it is not in use by any active [[screen objects]]. If a view is unloaded while still assigned to an object, AGI will most likely crash.
  
* if the view is not already [[Load.view();|loaded]], the game will crash with a [[View Not Loaded Error|View not loaded error]]
+
Because of the way that AGI manages memory on the [[memory heap|heap]], resources must be unloaded in reverse order of the way they were originally loaded, or unexpected results may occur.
* if the view is assigned to an [[Object|object]] when it is discarded, the game may crash or exhibit other odd behavior; it may not even generate an error message
 
* [[Resources|resources]] must be discarded in exactly the reverse order that they were loaded, or subsequent discard.view commands may generate a [[View Not Loaded Error|view not loaded error]], ''even if the view has actually been loaded''; see [[Memory and Script]] for more details on this issue
 
* the <code>discard.view</code> and <code>discard.view.v</code> commands add to the [[Script Buffer|script buffer]]; this can cause a [[Script Buffer Overflow Error|script buffer overflow error]].
 
  
&nbsp;
+
Attempting to discard a resource that has not been loaded will raise [[trappable error #1]].
  
== Examples ==
+
== Example ==
  
The following example uses <code>discard.view</code> to remove view 203 from memory:
+
<div class="CodeBlockHeader">Code:</div>
 +
<syntaxhighlight lang="agi">
 +
load.view(8) [ load view 8
 +
...
 +
[ do something with it
 +
...
 +
[ make sure view 8 is no longer used before unloading
 +
discard.view(8);
 +
</syntaxhighlight>
  
<code>load.view(203);
+
== Technical Information ==
discard.view(203);</code>
 
  
The next example uses <code>discard.view.v</code> to accomplish the same task:
+
{| border="1" cellpadding="2"
 +
| style="background-color: #efefef" width="200" | '''Required Interpreter Version:'''
 +
| width="175" | Available in all AGI versions.
 +
|-
 +
| style="background-color: #efefef" | '''Byte-Code Value:'''
 +
| 32 (0x20 hex)
 +
|}
  
<code>load.view(203);
+
== See Also ==
v100 = 203;
 
discard.view.v(v100);</code>
 
  
 
+
[[Screen Object/View Commands]]<br />
== See also ==
+
'''[[discard.view.v]]'''<br />
 
+
'''[[load.view]]'''<br />
* [[load.view();]]
+
'''[[load.view.v]]'''<br />
 
+
'''[[set.view]]'''<br />
&nbsp;
+
'''[[set.view.v]]'''<br />
 
+
[[Category:Commands]]<br />
== Sources ==
 
 
 
Some of the text in the article is taken from the AGI Studio help file.
 

Latest revision as of 09:54, 30 March 2019

The discard.view command unloads a view resource from the memory heap.

Syntax

discard.view(byt A);

Remarks

This command takes a number as the argument. View A is unloaded from memory.

The discard.view.v command also unloads views, but takes a variable as the argument.

AGI adds a script entry to the script stack each time a view resource is unloaded.

Possible Errors

Before unloading a view, make certain it is not in use by any active screen objects. If a view is unloaded while still assigned to an object, AGI will most likely crash.

Because of the way that AGI manages memory on the heap, resources must be unloaded in reverse order of the way they were originally loaded, or unexpected results may occur.

Attempting to discard a resource that has not been loaded will raise trappable error #1.

Example

Code:

<syntaxhighlight lang="agi"> load.view(8) [ load view 8 ... [ do something with it ... [ make sure view 8 is no longer used before unloading discard.view(8); </syntaxhighlight>

Technical Information

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

See Also

Screen Object/View Commands
discard.view.v
load.view
load.view.v
set.view
set.view.v