The description of @print_table in ZMS 1.1 is quite spare:
Print a rectangle of text on screen spreading right and down from the current cursor position, of given width and height, from the table of ZSCII text given. (Height is optional and defaults to 1.) If a skip value is given, then that many characters of text are skipped over in between each line and the next. (So one could make this display, for instance, a 2 by 3 window onto a giant 40 by 40 character graphics map.)
Its behavior seems to vary across different interpreters, which is perhaps understandable given the above. Is there any additional documentation on this opcode anywhere? If not, can anyone answer:
What kind of memory structure is referred to as a “table” in the above?
What constitutes a “line” in the above?
What does it mean for a character to be “skipped over” in the above?
The terminology of “table” and “line” seems similar to that used when describing the @print_form opcode, but the behavior of the two opcodes is quite different when feeding the same data structure to both (at least on Frotz 2.53 and WinFrotz 1.21), so it’s not clear that it is supposed to be the same kind of table.
Skip skips over existing printed characters before printing the text from the table. If skip is 5, then every printed line of the table will begin on the sixth column of the screen.
@Mike_G, thank you for the response. Will you cite an interpreter that behaves as you describe? None of Frotz 2.53, WinFrotz 1.21 or Bocfel 1.3.2 seems to operate in that manner.
Here’s the test code I was using to try to figure out what @print_table actually does:
Test Code
Constant Story "print_table test";
Constant Headline "^(an underdocumented Z-machine feature)^";
Include "Parser";
Include "VerbLib";
Include "Grammar";
Constant FORMSIZE = 500;
Array sample_table buffer FORMSIZE;
Global table_pointer = 0;
Array temp_text buffer 150;
Class Room
has light;
Room Start "Starting Point"
with description
"An uninteresting room.";
[ AddToTable str tmpbuf loc i ;
str.print_to_array(tmpbuf); ! temporary storage
loc = sample_table + table_pointer; ! set pointer to start of entry
! print "<tmpbuf-->0 = ", tmpbuf-->0, ">^";
loc-->0 = tmpbuf-->0; ! copy length to table
! print "<copying: ";
for (i=0: i<(tmpbuf-->0): i++) { ! copy data to table
loc->(i+WORDSIZE) = tmpbuf->(i+WORDSIZE);
! print (char) tmpbuf->(i+WORDSIZE);
}
! print ">^";
table_pointer = table_pointer+WORDSIZE+((sample_table+table_pointer)-->0);
! print "<new pointer = ", table_pointer, ">^";
];
[ Initialise ;
location = Start;
AddtoTable("abc", temp_text);
AddtoTable("123", temp_text);
AddtoTable("TUVWXYZ", temp_text);
print "^<print_table 5 x 5>^";
@print_table sample_table 5 5;
print "^<print_table 5 x 10>^";
@print_table sample_table 5 10;
print "^<print_table 10 x 5>^";
@print_table sample_table 10 5;
print "^<print_table 10 x 10>^";
@print_table sample_table 10 10;
print "^<print_table 5 x 5 skip 3>^";
@print_table sample_table 5 5 3;
print "^<print_table 10 x 10 skip 3>^";
@print_table sample_table 10 10 3;
];
In particular, the calls that make use of the skip parameter seem to consistently produce problematic results across multiple interpreters.
Note that the “table” construct is assembled to contain multiple buffer-like arrays laid end-to-end, as would be used with @print_form. If @print_table is supposed to operate on only one such “table” (i.e. one buffer-like array) then presumably anything past the length indicated by the initial word shouldn’t matter.
Ah, okay, the problem is that here “table of zscii text” does not mean “a size word followed by content”. The core point is that the functionality of @print_table is “print this array of ZSCII laid out in tabular form” not “print out these tables”. The use of “table” here is unfortunate, it would be better if the opcode were something like “print_grid” and the specification gave the first argument as “grid of zscii text” or just “array of zscii text”. The first argument should just be an array of the ZSCII characters that form the table / grid.
PRINTT takes a table of bytes, a width (a number of columns) and optionally a height (a number of lines), which is assumed to be one if omitted. It also optionally takes a skip, which is how many bytes of atable to skip over at the end of each line (by default, none).
It prints, in a block at the current cursor position, bytes from the table. Each group of width bytes is printed on a separate line aligned with the first, until height lines have been printed. Each time widthbytes have been printed, skip bytes are skipped over. The skipparameter allows a rectangular block of text from anywhere within a rectangular table (one where the rows are stored) to be printed.
However, in reading this, you’ve got to bear in mind what this document means by “table”. From page 19:
Tables are in fact only a useful logical concept and have no physical form in the Z-machine. (However the assembler, ZAP and debugging ZIPs, do “know” about tables.) Table pointers are simply byte-pointers to appropriate locations in the Z program.
…
Offsets in tables are zero-based. The first element of a table is element zero, the second is element 1, and so on.
You are right about the unfortunate use of the term table. The standard describes a table is 15.2 as “Specifically, a table is an array of words (in dynamic or static memory) of which the initial entry is the number of subsequent words in the table.”
Looking back at the last time I implemented this (a long time ago), I can see it is just raw text with no size indicator as you described.
Thank you once again for the critical clarifying information, @DavidK! (And for the link to the YZIP documentation.) It’s now a lot clearer what the intended usage of the opcode is.
That’s not what he said. He said the sentence “PRINTT with a height greater than one may only be used in screen 1.” is in the x-zip spec but not in the y-zip spec.
Yes, this is what I meant. Moreover, it isn’t very clear to me what happens when buffering is on and height is > 1 (as I’m not very familiar with the v6 screen model). I remember this led to some peculiar results with Praxix trying to use it in the lower window (v5).
I hope I’m not doing anything wrong in reviving this topic, but since it’s about exactly the same thing:
Praxix’s @print_table test (it’s the first one if you enter the command “tables”) has different behaviors depending on the interpreter:
On Frotz 2.53 on Linux, Windows Frotz 1.22 on Windows, and the latest Gargoyle+bocfel on Linux, the test prints the alphabet in upper case in one line, and then the same in lower case in a different line.
On Ozmoo (the latest releases for both C64 and BBC Micro), and on Zxzvm 1.17 on the ZX Spectrum Next, it prints everything in a single line (i.e. “…WXYZabcd…”).
Which behavior is the correct one?
The line in question, in the Praxix source, seems to be:
@print_table val 26 2 6;
Assuming the “2” is the number of rows, it should split the alphabets into two lines, right?
Thanks!
Now I’ve checked the Praxix source, and at least in the version I have, all output happens in the lower window. Using print_table with a height > 1 in the lower window is illegal according to Infocom’s specification and will probably be declared illegal in the modern-day Z-machine specification v1.2. The reason is that the lower window has wordwrap, it may have a proportional font and you can’t read or set the cursor position, so it’s tricky to print a multi-row table like this in a predictable way across platforms.
When performing illegal operations, the results may indeed vary across interpreters.
Thanks for the explanation, @fredrik ! So, if I understand correctly, Praxix is attempting something illegal there, which some interpreters accept, and others (correctly) don’t? If that is so, it’s funny that the modern 8-bit interpreters are apparently the ones doing it right. Though it’s probably not worth it to bother the Frotz/Bocfel maintainers about this, correct?
Though it’s probably not worth it to bother the Frotz/Bocfel maintainers about this, correct?