Skool macros¶
skool files and ref files may contain skool macros that are ‘expanded’ to an appropriate piece of HTML markup (when rendering in HTML mode), or to an appropriate piece of plain text (when rendering in ASM mode).
Skool macros have the following general form:
#MACROrparam1,rparam2,...[,oparam1,oparam2,...]
where:
- MACRO is the macro name
- rparam1, rparam2 etc. are required parameters
- oparam1, oparam2 etc. are optional parameters
If an optional parameter is left blank or omitted entirely, it assumes its default value. So, for example:
#UDG39144
is equivalent to:
#UDG39144,56,4,1,0,0,0,1
and:
#UDG30115,,2
is equivalent to:
#UDG30115,56,2
Numeric parameters may be given in decimal notation (as already shown in the examples above), or in hexadecimal notation (prefixed by $):
#UDG$98E8,$06
General macros¶
#BUG¶
In HTML mode, the #BUG macro expands to a hyperlink (<a> element) to the ‘Bugs’ page, or to a specific entry on that page.
#BUG[#name][(link text)]
- #name is the named anchor of a bug (if linking to a specific one)
- link text is the link text to use
The anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
In HTML mode, if the link text is blank, the title of the bug entry (if linking to a specific one) is substituted; if the link text is omitted entirely, ‘bug’ is substituted.
In ASM mode, the #BUG macro expands to the link text, or ‘bug’ if the link text is blank or omitted.
For example:
42726 DEFB 130 ; This is a #BUG#bug1; it should be 188
In HTML mode, this instance of the #BUG macro expands to a hyperlink to an entry on the ‘Bugs’ page.
In ASM mode, this instance of the #BUG macro expands to ‘bug’.
| Version | Changes |
|---|---|
| 2.3.1 | If left blank, the link text defaults to the bug entry title in HTML mode |
#CALL¶
In HTML mode, the #CALL macro expands to the return value of a method on the HtmlWriter class or subclass that is being used to create the HTML disassembly (as defined by the HtmlWriterClass parameter in the [Config] section of the ref file).
In ASM mode, the #CALL macro expands to the return value of a method on the AsmWriter class or subclass that is being used to generate the ASM output (as defined by the @writer ASM directive in the skool file).
#CALL:methodName(args)
- methodName is the name of the method to call
- args is a comma-separated list of arguments to pass to the method
For example:
; The byte at address 32768 is #CALL:peek(32768).
This instance of the #CALL macro expands to the return value of the peek method (on the HtmlWriter or AsmWriter subclass being used) when called with the argument 32768.
For information on writing methods that may be called by a #CALL macro, see the documentation on extending SkoolKit.
| Version | Changes |
|---|---|
| 3.1 | Added support for ASM mode |
| 2.1 | New |
#CHR¶
In HTML mode, the #CHR macro expands to a numeric character reference (&#num;). In ASM mode, it expands to a unicode character in the UTF-8 encoding.
#CHRnum
or:
#CHR(num)
For example:
26751 DEFB 127 ; This is the copyright symbol: #CHR169
In HTML mode, this instance of the #CHR macro expands to ©. In ASM mode, it expands to the copyright symbol.
| Version | Changes |
|---|---|
| 3.1 | New |
#D¶
The #D (Description) macro expands to the title of an entry (a routine or data block) in the memory map.
#Daddr
- addr is the address of the entry.
For example:
; Now we make an indirect jump to one of the following routines:
; .
; #TABLE(default,centre)
; { =h Address | =h Description }
; { #R27126 | #D27126 }
This instance of the #D macro expands to the title of the routine at 27126.
#EREFS¶
The #EREFS (Entry point REFerenceS) macro expands to a comma-separated sequence of hyperlinks to (in HTML mode) or addresses of (in ASM mode) the routines that jump to or call a given address.
#EREFSaddr
- addr is the address to search for references to
See also #REFS.
| Version | Changes |
|---|---|
| 3.1 | Added support for ASM mode |
#FACT¶
In HTML mode, the #FACT macro expands to a hyperlink (<a> element) to the ‘Trivia’ page, or to a specific entry on that page.
#FACT[#name][(link text)]
- #name is the named anchor of a trivia entry (if linking to a specific one)
- link text is the link text to use
The anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
In HTML mode, if the link text is blank, the title of the trivia entry (if linking to a specific one) is substituted; if the link text is omitted entirely, ‘fact’ is substituted.
In ASM mode, the #FACT macro expands to the link text, or ‘fact’ if the link text is blank or omitted.
For example:
See the trivia entry #FACT#interestingFact() for details.
In HTML mode, this instance of the #FACT macro expands to a hyperlink to an entry on the ‘Trivia’ page, with link text equal to the title of the entry.
| Version | Changes |
|---|---|
| 2.3.1 | If left blank, the link text defaults to the trivia entry title in HTML mode; added support for ASM mode |
#HTML¶
The #HTML macro expands to arbitrary text (in HTML mode) or to an empty string (in ASM mode).
#HTML(text)
The #HTML macro may be used to render HTML (which would otherwise be escaped) from a skool file. For example:
; #HTML(For more information, go <a href="http://example.com/">here</a>.)
If text contains a closing bracket - ) - then the macro will not expand as required. In that case, square brackets, braces or any character that does not appear in text (except for an upper case letter) may be used as delimiters:
#HTML[text]
#HTML{text}
#HTML@text@
text may contain other skool macros, which will be expanded before rendering. For example:
; #HTML[The UDG defined here (32768) looks like this: #UDG32768,4,1]
See also #UDGTABLE.
| Version | Changes |
|---|---|
| 3.1.2 | New |
#LINK¶
In HTML mode, the #LINK macro expands to a hyperlink (<a> element) to another page.
#LINK:PageId[#name](link text)
- PageId is the ID of the page to link to
- name is the name of an anchor on the page to link to
- link text is the link text to use
In HTML mode, if the link text is blank, the page’s link text (as defined in the [Links] section or the relevant [Page:*] section of the ref file) is substituted.
In ASM mode, the #LINK macro expands to the link text.
The page IDs that may be used are the same as the file IDs that may be used in the [Paths] section of a ref file, or the page IDs defined by [Page:*] sections.
For example:
; See the #LINK:Glossary(glossary) for a definition of 'chuntey'.
In HTML mode, this instance of the #LINK macro expands to a hyperlink to the ‘Glossary’ page, with link text ‘glossary’.
In ASM mode, this instance of the #LINK macro expands to ‘glossary’.
| Version | Changes |
|---|---|
| 3.1.3 | If left blank, the link text defaults to the page’s link text in HTML mode |
| 2.1 | New |
#LIST¶
The #LIST macro marks the beginning of a list of bulleted items; LIST# is used to mark the end. Between these markers, the list items are defined.
#LIST[(class)]<items>LIST#
- class is the CSS class to use for the <ul> element
Each item in a list must start with { followed by a whitespace character, and end with } preceded by a whitespace character.
For example:
; #LIST(data)
; { Item 1 }
; { Item 2 }
; LIST#
This list has two items, and will have the CSS class ‘data’.
In ASM mode, lists are rendered as plain text, with each item on its own line, and an asterisk as the bullet character. The bullet character can be changed by using a @set directive to set the bullet property on the ASM writer.
| Version | Changes |
|---|---|
| 3.2 | New |
#POKE¶
In HTML mode, the #POKE macro expands to a hyperlink (<a> element) to the ‘Pokes’ page, or to a specific entry on that page.
#POKE[#name][(link text)]
- #name is the named anchor of a poke (if linking to a specific one)
- link text is the link text to use
The anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
In HTML mode, if the link text is blank, the title of the poke entry (if linking to a specific one) is substituted; if the link text is omitted entirely, ‘poke’ is substituted.
In ASM mode, the #POKE macro expands to the link text, or ‘poke’ if the link text is blank or omitted.
For example:
; Of course, if you feel like cheating, you can always give yourself
; #POKE#infiniteLives(infinite lives).
In HTML mode, this instance of the #POKE macro expands to a hyperlink to an entry on the ‘Pokes’ page, with link text ‘infinite lives’.
In ASM mode, this instance of the #POKE macro expands to ‘infinite lives’.
| Version | Changes |
|---|---|
| 2.3.1 | If left blank, the link text defaults to the poke entry title in HTML mode; added support for ASM mode |
#R¶
In HTML mode, the #R (Reference) macro expands to a hyperlink (<a> element) to the disassembly page for a routine or data block, or to a line at a given address within that page.
#Raddr[@code][#name][(link text)]
- addr is the address of the routine or data block (or entry point thereof)
- code is the ID of the disassembly that contains the routine or data block (if not given, the current disassembly is assumed; otherwise this must be an ID defined in an [OtherCode:*] section of the ref file)
- #name is the named anchor of an item on the disassembly page
- link text is the link text to use (default: addr)
The disassembly ID (code) and anchor name (name) must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
In ASM mode, the #R macro expands to the link text if it is specified, or to the label for addr, or to addr if no label is found.
For example:
; Prepare for a new game
;
; Used by the routine at #R25820.
In HTML mode, this instance of the #R macro expands to a hyperlink to the disassembly page for the routine at 25820.
In ASM mode, this instance of the #R macro expands to the label for the routine at 25820 (or simply 25820 if that routine has no label).
| Version | Changes |
|---|---|
| 3.5 | Added the ability to resolve (in HTML mode) the address of an entry point in another disassembly when an appropriate remote entry is defined |
| 2.0 | Added support for the @code notation |
#REFS¶
The #REFS (REFerenceS) macro expands to a comma-separated sequence of hyperlinks to (in HTML mode) or addresses of (in ASM mode) the routines that jump to or call a given routine, or jump to or call any entry point within that routine.
#REFSaddr[(prefix)]
- addr is the address of the routine to search for references to
- prefix is the text to display before the sequence of hyperlinks or addresses if there is at least one reference (default: no text)
If there are no references, the macro expands to the following text:
Not used directly by any other routines
See also #EREFS.
| Version | Changes |
|---|---|
| 3.1 | Added support for ASM mode |
| 1.0.6 | Added the prefix parameter |
#REG¶
In HTML mode, the #REG (REGister) macro expands to a styled <span> element containing a register name.
#REGreg
- reg is the name of the register (e.g. ‘a’, ‘bc’)
In ASM mode, the #REG macro expands to the name of the register.
The register name must contain 1, 2 or 3 of the following characters:
abcdefhlirspxy'
For example:
24623 LD C,31 ; #REGbc'=31
#SPACE¶
The #SPACE macro expands to one or more   expressions (in HTML mode) or spaces (in ASM mode).
#SPACE[num]
or:
#SPACE([num])
- num is the number of spaces required (default: 1)
For example:
; '#SPACE8' (8 spaces)
t56832 DEFM " "
In HTML mode, this instance of the #SPACE macro expands to:
        
In ASM mode, this instance of the #SPACE macro expands to a string containing 8 spaces.
The form SPACE([num]) may be used to distinguish the macro from adjacent text where necessary. For example:
; 'Score:#SPACE(5)0'
t49152 DEFM "Score: 0"
| Version | Changes |
|---|---|
| 2.4.1 | Added support for the #SPACE([num]) syntax |
#TABLE¶
The #TABLE macro marks the beginning of a table; TABLE# is used to mark the end. Between these markers, the rows of the table are defined.
#TABLE[([class[,class1[:w][,class2[:w]...]]])]<rows>TABLE#
- class is the CSS class to use for the <table> element
- class1, class2 etc. are the CSS classes to use for the <td> elements in columns 1, 2 etc.
Each row in a table must start with { followed by a whitespace character, and end with } preceded by a whitespace character. The cells in a row must be separated by | with a whitespace character on each side.
For example:
; #TABLE(default,centre)
; { 0 | Off }
; { 1 | On }
; TABLE#
This table has two rows and two columns, and will have the CSS class ‘default’. The cells in the first column will have the CSS class ‘centre’.
By default, cells will be rendered as <td> elements. To render a cell as a <th> element, use the =h indicator before the cell contents:
; #TABLE
; { =h Header 1 | =h Header 2 }
; { Regular cell | Another one }
; TABLE#
It is also possible to specify colspan and rowspan attributes using the =c and =r indicators:
; #TABLE
; { =r2 2 rows | X | Y }
; { =c2 2 columns }
; TABLE#
Finally, the =t indicator makes a cell transparent (i.e. gives it the same background colour as the page body).
If a cell requires more than one indicator, separate the indicators by commas:
; #TABLE
; { =h,c2 Wide header }
; { Column 1 | Column 2 }
; TABLE#
The CSS files included in SkoolKit provide two classes that may be used when defining tables:
- default - a class for <table> elements that provides a background colour to make the table stand out from the page body
- centre - a class for <td> elements that centres their contents
In ASM mode, tables are rendered as plain text, using dashes (-) and pipes (|) for the borders, and plus signs (+) where a horizontal border meets a vertical border.
ASM mode also supports the :w indicator in the #TABLE macro’s parameters. The :w indicator marks a column as a candidate for having its width reduced (by wrapping the text it contains) so that the table will be no more than 79 characters wide when rendered. For example:
; #TABLE(default,centre,:w)
; { =h X | =h Description }
; { 0 | Text in this column will be wrapped in ASM mode to make the table less than 80 characters wide }
; TABLE#
See also #UDGTABLE.
Image macros¶
The #FONT, #SCR, #UDG and #UDGARRAY macros (described in the following sections) may be used to create images based on graphic data in the memory snapshot. They are not supported in ASM mode.
These macros have several numeric parameters, most of which are optional. This can give rise to a long sequence of commas in a macro parameter string, making it hard to read (and write); for example:
#UDG32768,,,,,,1
To alleviate this problem, the image macros accept keyword arguments at any position in the parameter string; the #UDG macro above could be rewritten as follows:
#UDG32768,rotate=1
#FONT¶
In HTML mode, the #FONT macro expands to an <img> element for an image of text rendered in the game font.
#FONT[:(text)]addr[,chars,attr,scale][{CROP}][(fname)]
- text is the text to render (default: the 96 characters from code 32 to code 127)
- addr is the base address of the font graphic data
- chars is the number of characters to render (default: the length of text)
- attr is the attribute byte to use (default: 56)
- scale is the scale of the image (default: 2)
- CROP is the cropping specification (see Cropping)
- fname is the name of the image file (default: ‘font‘); ‘.png‘ or ‘.gif‘ will be appended (depending on the default image format specified in the [ImageWriter] section of the ref file) if not present
If text contains a closing bracket - ) - then the macro will not expand as required. In that case, square brackets, braces or any character that does not appear in text may be used as delimiters; for example:
#FONT:[(0) OK]$3D00
#FONT:{(0) OK}$3D00
#FONT:/(0) OK/$3D00
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the FontImagePath parameter in the [Paths] section of the ref file.
For example:
; Font graphic data
;
; #HTML[#FONT:(0123456789)49152]
In HTML mode, this instance of the #FONT macro expands to an <img> element for the image of the digits 0-9 in the 8*8 font whose graphic data starts at 49152.
| Version | Changes |
|---|---|
| 4.0 | Added support for keyword arguments |
| 3.6 | Added the text parameter, and made the chars parameter optional |
| 3.0 | Added image-cropping capabilities |
| 2.0.5 | Added the fname parameter and support for regular 8x8 fonts |
#SCR¶
In HTML mode, the #SCR (SCReenshot) macro expands to an <img> element for an image constructed from the display file and attribute file (or suitably arranged graphic data and attribute bytes elsewhere in memory) of the current memory snapshot (in turn constructed from the contents of the skool file).
#SCR[scale,x,y,w,h,df,af][{CROP}][(fname)]
- scale is the scale of the image (default: 1)
- x is the x-coordinate of the top-left tile of the screen to include in the screenshot (default: 0)
- y is the y-coordinate of the top-left tile of the screen to include in the screenshot (default: 0)
- w is the width of the screenshot in tiles (default: 32)
- h is the height of the screenshot in tiles (default: 24)
- df is the base address of the display file (default: 16384)
- af is the base address of the attribute file (default: 22528)
- CROP is the cropping specification (see Cropping)
- fname is the name of the image file (default: ‘scr‘); ‘.png‘ or ‘.gif‘ will be appended (depending on the default image format specified in the [ImageWriter] section of the ref file) if not present
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the ScreenshotImagePath parameter in the [Paths] section of the ref file.
For example:
; #UDGTABLE
; { #SCR(loading) | This is the loading screen. }
; TABLE#
| Version | Changes |
|---|---|
| 4.0 | Added support for keyword arguments |
| 3.0 | Added image-cropping capabilities and the df and af parameters |
| 2.0.5 | Added the scale, x, y, w, h and fname parameters |
#UDG¶
In HTML mode, the #UDG macro expands to an <img> element for the image of a UDG (an 8x8 block of pixels).
#UDGaddr[,attr,scale,step,inc,flip,rotate,mask][:MASK][{CROP}][(fname)]
- addr is the base address of the UDG bytes
- attr is the attribute byte to use (default: 56)
- scale is the scale of the image (default: 4)
- step is the interval between successive bytes of the UDG (default: 1)
- inc is added to each UDG byte before constructing the image (default: 0)
- flip is 1 to flip the UDG horizontally, 2 to flip it vertically, 3 to flip it both ways, or 0 to leave it as it is (default: 0)
- rotate is 1 to rotate the UDG 90 degrees clockwise, 2 to rotate it 180 degrees, 3 to rotate it 90 degrees anticlockwise, or 0 to leave it as it is (default: 0)
- mask is the type of mask to apply (see Masks)
- MASK is the mask specification (see below)
- CROP is the cropping specification (see Cropping)
- fname is the name of the image file (if not given, a name based on addr, attr and scale will be generated); ‘.png‘ or ‘.gif‘ will be appended (depending on the default image format specified in the [ImageWriter] section of the ref file) if not present
The mask specification (MASK) takes the form:
addr[,step]
- addr is the base address of the mask bytes to use for the UDG
- step is the interval between successive mask bytes (defaults to the value of step for the UDG)
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the UDGImagePath parameter in the [Paths] section of the ref file.
For example:
; Safe key UDG
;
; #HTML[#UDG39144,6(safe_key)]
In HTML mode, this instance of the #UDG macro expands to an <img> element for the image of the UDG at 39144 (which will be named safe_key.png or safe_key.gif), with attribute byte 6 (INK 6: PAPER 0).
| Version | Changes |
|---|---|
| 4.0 | Added the mask parameter and support for AND-OR masking; added support for keyword arguments |
| 3.1.2 | Made the attr parameter optional |
| 3.0 | Added image-cropping capabilities |
| 2.4 | Added the rotate parameter |
| 2.3.1 | Added the flip parameter |
| 2.1 | Added support for masks |
| 2.0.5 | Added the fname parameter |
#UDGARRAY¶
In HTML mode, the #UDGARRAY macro expands to an <img> element for the image of an array of UDGs (8x8 blocks of pixels).
#UDGARRAYwidth[,attr,scale,step,inc,flip,rotate,mask];SPEC1[;SPEC2;...][{CROP}](fname)
- width is the width of the image (in UDGs)
- attr is the default attribute byte of each UDG (default: 56)
- scale is the scale of the image (default: 2)
- step is the default interval between successive bytes of each UDG (default: 1)
- inc is added to each UDG byte before constructing the image (default: 0)
- flip is 1 to flip the array of UDGs horizontally, 2 to flip it vertically, 3 to flip it both ways, or 0 to leave it as it is (default: 0)
- rotate is 1 to rotate the array of UDGs 90 degrees clockwise, 2 to rotate it 180 degrees, 3 to rotate it 90 degrees anticlockwise, or 0 to leave it as it is (default: 0)
- mask is the type of mask to apply (see Masks)
- CROP is the cropping specification (see Cropping)
- fname is the name of the image file; ‘.png‘ or ‘.gif‘ will be appended (depending on the default image format specified in the [ImageWriter] section of the ref file) if not present
SPEC1, SPEC2 etc. are UDG specifications for the sets of UDGs that make up the array. Each UDG specification has the form:
addr[,attr,step,inc][:MASK]
- addr is the address range specification for the set of UDGs (see below)
- attr is the attribute byte of each UDG in the set (defaults to the value of attr for the UDG array)
- step is the interval between successive bytes of each UDG in the set (defaults to the value of step for the UDG array)
- inc is added to each byte of every UDG in the set before constructing the image (defaults to the value of inc for the UDG array)
- MASK is the mask specification
The mask specification (MASK) takes the form:
addr[,step]
- addr is the address range specification for the set of mask UDGs (see below)
- step is the interval between successive bytes of each mask UDG in the set (defaults to the value of step for the set of UDGs)
Address range specifications (addr) may be given in one of the following forms:
- a single address (e.g. 39144)
- a simple address range (e.g. 33008-33015)
- an address range with a step (e.g. 32768-33792-256)
- an address range with a horizontal and a vertical step (e.g. 63476-63525-1-16; this form specifies the step between the base addresses of adjacent UDGs in each row as 1, and the step between the base addresses of adjacent UDGs in each column as 16)
Any of these forms of address ranges can be repeated by appending xN, where N is the desired number of repetitions. For example:
- 39648x3 is equivalent to 39648;39648;39648
- 32768-32769x2 is equivalent to 32768;32769;32768;32769
As many UDG specifications as required may be supplied, separated by semicolons; the UDGs will be arranged in a rectangular array with the given width.
If an image with the given filename doesn’t already exist, it will be created. If fname starts with a ‘/’, the filename is taken to be relative to the root of the HTML disassembly; otherwise the filename is taken to be relative to the directory defined by the UDGImagePath parameter in the [Paths] section of the ref file.
For example:
; Base sprite
;
; #HTML[#UDGARRAY4;32768-32888-8(base_sprite.png)]
In HTML mode, this instance of the #UDGARRAY macro expands to an <img> element for the image of the 4x4 sprite formed by the 16 UDGs with base addresses 32768, 32776, 32784 and so on up to 32888; the image file will be named base_sprite.png.
| Version | Changes |
|---|---|
| 4.0 | Added the mask parameter and support for AND-OR masking; added support for keyword arguments |
| 3.6 | Added support for creating an animated image from an arbitrary sequence of frames |
| 3.1.1 | Added support for UDG address ranges with horizontal and vertical steps |
| 3.0 | Added image-cropping capabilities |
| 2.4 | Added the rotate parameter |
| 2.3.1 | Added the flip parameter |
| 2.2.5 | Added support for masks |
| 2.0.5 | New |
Animation¶
The #UDGARRAY macro may be used to create an animated image from an arbitrary sequence of frames. To create a frame, the fname parameter must have one of the following forms:
- name* - writes an image file with this name, and also creates a frame with the same name
- name1*name2 - writes an image file named name1, and also creates a frame named name2
- *name - writes no image file, but creates a frame with this name
Then a special form of the #UDGARRAY macro is used to create the animated image from a set of frames:
#UDGARRAY*FRAME1[;FRAME2;...](fname)
FRAME1, FRAME2 etc. are frame specifications; each one has the form:
name[,delay]
- name is the name of the frame
- delay is the delay between this frame and the next in 1/100ths of a second; it also sets the default delay for any frames that follow (default: 32)
For example:
; Sprite animation frames
;
; #UDGTABLE {
; #UDGARRAY2;64000-64024-8(sprite1*) |
; #UDGARRAY2;64032-64056-8(sprite2*) |
; #UDGARRAY2;64064-64088-8(sprite3*) |
; #UDGARRAY*sprite1,50;sprite2;sprite3(sprite.gif)
; } TABLE#
The first three #UDGARRAY macros create the required frames (and write images of them); the last #UDGARRAY macro combines the three frames into a single animated image, with a delay of 0.5s between each frame.
Cropping¶
Each image macro accepts a cropping specification (CROP) which takes the form:
x,y,width,height
- x is the x-coordinate of the leftmost pixel column of the constructed image to include in the final image (default: 0); if greater than 0, the image will be cropped on the left
- y is the y-coordinate of the topmost pixel row of the constructed image to include in the final image (default: 0); if greater than 0, the image will be cropped on the top
- width is the width of the final image in pixels (default: width of the constructed image)
- height is the height of the final image in pixels (default: height of the constructed image)
For example:
#UDG40000,scale=2{2,2,12,12}
This #UDG macro creates an image of the UDG at 40000, at scale 2, with the top two rows and bottom two rows of pixels removed, and the leftmost two columns and rightmost two columns of pixels removed.
Masks¶
The #UDG and #UDGARRAY macros accept a mask parameter that determines what kind of mask to apply to each UDG. The supported values are:
- 0 - no mask
- 1 - OR-AND mask (this is the default)
- 2 - AND-OR mask
Given a ‘background’ bit (B), a UDG bit (U), and a mask bit (M), the OR-AND mask works as follows:
- OR the UDG bit (U) onto the background bit (B)
- AND the mask bit (M) onto the result
| U | M | Result |
|---|---|---|
| 0 | 0 | 0 (paper) |
| 0 | 1 | B (transparent) |
| 1 | 0 | 0 (paper) |
| 1 | 1 | 1 (ink) |
The AND-OR mask works as follows:
- AND the mask bit (M) onto the background bit (B)
- OR the UDG bit (U) onto the result
| U | M | Result |
|---|---|---|
| 0 | 0 | 0 (paper) |
| 0 | 1 | B (transparent) |
| 1 | 0 | 1 (ink) |
| 1 | 1 | 1 (ink) |
By default, transparent bits in masked images are rendered in bright green (#00fe00); this colour can be changed by modifying the TRANSPARENT parameter in the [Colours] section. To make the transparent bits in masked images actually transparent, set GIFTransparency=1 or PNGAlpha=0 in the [ImageWriter] section.
Snapshot macros¶
The #POKES, #POPS and #PUSHS macros (described in the following sections) may be used to manipulate the memory snapshot that is built from the DEFB, DEFM, DEFS and DEFW statements in the skool file. Each macro expands to an empty string.
#POKES¶
The #POKES (POKE Snapshot) macro POKEs values into the current memory snapshot.
#POKESaddr,byte[,length,step][;addr,byte[,length,step];...]
- addr is the address to POKE
- byte is the value to POKE addr with
- length is the number of addresses to POKE (default: 1)
- step is the address increment to use after each POKE (if length>1; default: 1)
For example:
The UDG looks like this:
#UDG32768(udg_orig)
But it's supposed to look like this:
#PUSHS
#POKES32772,254;32775,136
#UDG32768(udg_fixed)
#POPS
This instance of the #POKES macro does POKE 32772,254 and POKE 32775,136, which fixes a graphic glitch in the UDG at 32768.
| Version | Changes |
|---|---|
| 3.1 | Added support for ASM mode |
| 2.3.1 | Added support for multiple addresses |
#POPS¶
The #POPS (POP Snapshot) macro removes the current memory snapshot and replaces it with the one that was previously saved by a #PUSHS macro.
#POPS
| Version | Changes |
|---|---|
| 3.1 | Added support for ASM mode |
#PUSHS¶
The #PUSHS (PUSH Snapshot) macro saves the current memory snapshot, and replaces it with an identical copy with a given name.
#PUSHS[name]
- name is the snapshot name (defaults to an empty string)
The snapshot name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z; it must not start with a capital letter.
| Version | Changes |
|---|---|
| 3.1 | Added support for ASM mode |