Specifying Gargoyle's Glk extensions

I have started specifying Gargoyle’s Glk extensions so that they can be exposed directly to the VMs for all of you to use, and perhaps for them to be implemented in other interpreters in the future. For now I’m specifying the text formatting functions, which is what has been most under demand!

Have a look at the specification, and let me know if you think it needs any clarifications.

I’ll be posting example code soon.

Edit: example code at github.com/curiousdannii/if/blo … e-text.inf

1 Like

This seems like a good idea! It all looks pretty straightforward, except for “zcolor_Transparent (-4)”. Is that actually useful or even useable at all? “Transparent” was only supported by Z-code V6 and used for overlaying text onto images, but with Glk as it currently is, I don’t see how you could usefully use “transparent” at the moment.

garglk itself just completely ignores both zcolor_Transparent and zcolor_Cursor. Maybe it would be better to leave them out of what I’m specifying here? If, in some distant future, they ever become useful it would be easy to add them back because it would be a backwards-compatible change.

Leaving them out makes sense - I’d forgotten that zcolor_Cursor is only really of use in the same way as zcolor_Transparent. If we’re not going to have any use for them yet, and no-one implements it, let;s leave it out.

Okay, I’ve removed zcolor_Cursor and zcolor_Transparent.

A further suggestion for clarification: what happens after glk_set_style() is called after a garglk_set_zcolors() call? Does the over-ride of the style colours remain, or do we reset back to what’s in the Glk style hints? I would favour the latter, but the most important thing is to specify one way or another…

From reading Gargoyle’s cgstream.c the garglk_set_zcolors colours (as well as reverse) stay in place even after calling glk_set_style. Perhaps not ideal, but at least it’s fairly self contained.

I’m having trouble building Gargoyle currently, but I’ll try to test it soon, and then update the spec and test file.

I’ve implemented these text formatting opcodes in Windows Glk, so that they can be used with the latest builds of Windows Glulxe and Windows Git, which are available from here:

Windows Glulxe: http://ifarchive.org/indexes/if-archiveXprogrammingXglulxXinterpretersXglulxe.html
Windows Git: http://ifarchive.org/indexes/if-archiveXprogrammingXglulxXinterpretersXgit.html

This would perhaps have been more use about 15 years ago, but better late than never …


Sorry I haven’t updated the unit test yet. I’m still planning to. I also want to make an Inform 7 extension.

Hi David, sorry it took so long, but I’ve checked how Garglk handles conflicting instructions from stylehints and these text functions. Unfortunately it’s a bit messy. Here’s what I added to the spec:

I’ve updated the test file to test all the combinations I could think of: github.com/curiousdannii/if/blo … e-text.ulx

I was concerned that you might have made Windows-Glk make garglk_set_reversevideo(0) overwrite a stylehint, but you followed what Garglk does, and the testcase runs correctly! :slight_smile:

And I’ve written an I7 extension: github.com/i7/extensions/blob/m … atting.i7x

Unfortunately it doesn’t look like it will be possible to make an inline colour change (like [colour #ff0000] or [colour “#ff0000”]). It would be possible to have say phrases for the colour functions, but they’d need to use text variables/constants rather than inline texts. I thought that would be too confusing so didn’t add the phrases.

If no one has any trouble with it, I’ll submit it to the PL soon.

Thanks for specifying this. The ability to change foreground and background colors on the fly is great, and something I dearly miss in plain glk.

So unfortunately I only just realised that I never described part of Garglk’s behaviour with its colour extensions: namely that when you call glk_window_clear the whole window should then be coloured with its background colour. There is a some inconsistent behaviour between the few Glk implementations that added these functions, and it would be good if we can sort out what should happen. Clearly no game authors are depending on that behaviour or else we would’ve noticed by now, but terps like Bocfel do I believe, and I intend to use this feature in the Glk TADS port in the future.

Glk library Sets background colour after clearing Sets background colour after clearing with other styles Sets page margins (outside windows)
Garglk Yes No Yes
My GlkOte fork Yes Yes No
Windows Glk No No N/A
Spatterlight ? (can someone please test for me?) ? ?

I just updated the test file to test for this: if/gargoyle-text.ulx at master · curiousdannii/if · GitHub

The Garglk option is quite odd - it appears that it will change the window background colour to the last background colour of the batch of output, rather than whatever was in place when glk_window_clear was called. Despite this being about specifying the Garglk extensions, this feels buggy to me. It would make more sense to me if the custom colour at the time of the window clearing was applied, even if the style is changed afterwards.

There’s also the question of whether it should set the page margins (ie, spaces around the Glk Windows). When I was working on colour support for my ZVM (for Parchment) I must have thought that Garglk didn’t set the page margins colour with the garglk_set_zcolors, as I used the other method, of setting a background colour stylehint for style_Normal. I don’t know for the page margins whether Garglk considers the zcolor to overrule the stylehint colour (as it does for text), or whether it’s just whichever is last set…

It would be nice to standardise these extra behaviours, even if they don’t get into published releases very quickly.

1 Like

Yeah, the Gargoyle behaviour doesn’t sound like something we’d want to codify. But that does mean fixing it in Gargoyle!

1 Like

This is what the last test looks like in Spatterlight:

1 Like

I agree there’s something broken with Gargoyle’s colors. I reported a bug over 10 years ago about colors, but it’s never been a high priority. I poke at the code every now and again, but I haven’t put a lot of time into it.

Colors ought to be specified in such a way that they make the most sense (i.e not Gargoyle’s version!) and I’ll try to get Gargoyle adhering to whatever the result is.

1 Like

Some suggested rules, which I’m not completely set on.

  1. A background colour stylehint for text buffers applied to the normal style will set the window margins (if applicable) to that colour. This applies at any time, even if called immediately before glk_select. It does not however change the background colour of any existing windows.
  2. Calling garglk_set_zcolors before glk_window_clear will both change the background colour of the window, and if applied to a text buffer window, also change the colour of the window margins.
  3. When both are used, whichever is called latest will apply its colour to the window margins.

I expanded the test file to test these rules: https://github.com/curiousdannii/if/raw/37254d5b046dd4675ebd6bcc2421a2dc8d438050/tests/gargoyle-text.ulx

Test 1: Setting window margins with a stylehint
Test 2: Setting window margins with garglk_set_zcolors, then a stylehint
Test 3: Setting window margins with a stylehint, then with garglk_set_zcolors
Test 4: Foreground colour and text styles
Test 5: Use garglk_set_zcolors after clearing the window
Test 6: Test clearing styles after clearing the window

Glk library Test 1 Test 2 Test 3 Test 4 Test 5 Test 6
Garglk :x:1 :x:2 :heavy_check_mark: :heavy_check_mark: :x:3 :x:2
My GlkOte fork :heavy_check_mark: :heavy_check_mark: :x:4 :x:4 :heavy_check_mark: :x:4
Windows Glk N/A :x:2 :x:2 :x:2 :heavy_check_mark: :x:2
Spatterlight :x:4 :x:4 :heavy_check_mark: :heavy_check_mark: :x:3 :heavy_check_mark:


  1. Doesn’t work unless you click in the window
  2. Window background colour is wrong
  3. Window background and margins are wrong
  4. Window margin is wrong

My GlkOte fork has one consistent issue - garglk_set_zcolors doesn’t set the window margins. Likewise Windows Glk doesn’t set the background colour after clearing the screen. Garglk however has several weird behaviours, including not setting the window margins if you have never clicked in the window!

I’m not sure I like the distinction between the window margin and the window background. Wouldn’t you expect them to be the same colour?

The “margin” is space completely outside the whole Glk window system. It’s not really part of the Glk model, but many interpreters have it. Each window can have its own background colour, and it may not be obvious from a programming perspective which window is meant to be the main one. Garglk took the last stylehint and applied it to the margins (though I now see it doesn’t do so perfectly consistently), and that’s since become an unofficial convention. Flexible Windows for example has a phrase to set the margin colour (though it calls it “Gargoyle window padding”, not margins).

Garglk by default only has margins of 20px or so, on each side. Parchment has no top and bottom margins, but can have wide side margins on any screen wider than 960px. (I will add an option to Parchment in the future to switch to full width as that’s better for some games, like Counterfeit Monkey with its side map.) Windows Glk doesn’t have margins, so all of that can be ignored.

If anyone has ideas for clearer terminology that would be great!


It is a bit confusing, because the Gargoyle settings list two kinds of margin, wmargin, “space around the window frame” and tmargin, “internal margin of text windows”. Here we are talking about the former.

Spatterlight calls it border, and has complicated heuristics to determine which window’s background colour to use as border colour, but it seems to work well most of the time. Not with this test, though. The border colour is always the same as the window background colour, which I think means that it fails the first two tests.