Theme file format

Anything QL Software or Programming Related.
Post Reply
User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Theme file format

Post by pjw »

As you may know, Wman2 offers four inbuilt system palettes, 0..3. These help to ensure some semblance of aesthetical sanity, in that all programs using Wman will sport only one of four liveries. (It is, however, also possible to create liveries on a per job basis if you wish.)

It is easy to create your own colour schemes - or themes - by using the excellent QCoCo app by Bob Spelten and Wolfgang Uhlig (http://members.upc.nl/b.spelten/ql/) The same format as produced by QCoCo can be used to change the inbuilt system palettes according to taste and to create bespoke palettes for specific programs.

You can test various system palettes from within QCoCo, and once satisfied, save them to disk and load them at boot time. I use the following routine, called from my stage 1 boot program:

Code: Select all

100 REMark Set all four Wman palettes
110 :
120 home$ = 'win2_util_col_coco_thms_'
130 ext$ = '_thm'
140 :
150 SetPal "grey", 0
160 SetPal "copper", 1
170 SetPal "meanie", 2
180 SetPal "blue", 3
190 QUIT
200 :
210 DEFine PROCedure SetPal(fnm$, palno%)
220 ch = FOP_IN(home$ & fnm$ & ext$): ERT ch
230 num = SP_GETCOUNT
240 mem = ALCHP(num * 2)
250 :
260 FOR adr = mem TO mem + (num - 1) * 2 STEP 2
270  INPUT#ch; col$
280  POKE_W adr, HEX(col$(2 TO))
290 END FOR adr
300 :
310 SP_SET palno%, mem, 0, num
320 RECHP mem
330 CLOSE#ch
340 END DEFine SetPal
350 :
This loads and sets the four system palettes that all PE program on my system use. You will have noticed that the format for these themes is simply a text file with a list of hex numbers:

$482
$DAAE
$0
$0
$5029
.. etc, SP_GETCOUNT (currently 57) items long in all.

This may be convenient, but not very efficient, as a list of 57 binary words may be loaded in a jiffy by LBYTES. Faster and consuming less space.

After discussion with Bob, I proposed the following additional format which, once finalised, will be supported by QCoCo too:

The file extension will be _thb - for theme binary

The proposed THB File Definition will be (described in assembler):

Code: Select all

dc.l 'TH01'   ; Flag and version number
dc.w $200     ; sp_winbd% - Window border
..            ; etc
the new SetPalB procedure might then look like this:

Code: Select all

100 DIM thv$(4): thv$(0) = 4
110 :
120 REMark Set all four Wman palettes
130 :
140 home$ = 'win2_util_col_coco_thms_'
150 ext$ = '_thb'
160 :
170 ERT SetPalB("grey", 0):       REMark System palette 0
180 ERT SetPalB("copper", 1):     REMark System palette 1
190 ERT SetPalB("meanie", 2):     REMark etc
200 ERT SetPalB("blue", 3)
210 QUIT
220 :
230 DEFine FuNction SetPalB(fnm$, palno%)
240 thc = FOP_IN(home$ & fnm$ & ext$)
250 IF thc < 0: RETurn thc
260 BGET#thc; thv$(1 TO 4): thl = FLEN(#thc): CLOSE#thc
270 IF NOT (thv$ = 'TH01' AND thl = SP_GETCOUNT * 2 + 4): RETurn -12
280 tha = ALCHP(thl)
290 LBYTES home$ & fnm$ & ext$, tha
300 SP_SET palno%, tha + 4, 0, SP_GETCOUNT
310 RECHP tha
320 RETurn 0
330 END DEFine SetPalB
340 :
In a program where youd like to have a job-specific palette, you could use something like:

Code: Select all

DIM thv$(4): thv$(0) = 4
..
thc = FOP_IN(theme$)
BGET#thc; thv$(1 TO 4): thl = FLEN(#thc): CLOSE#thc
IF thv$ = 'TH01' AND thl = SP_GETCOUNT * 2 + 4 THEN
 tha = ALCHP(thl)
 LBYTES theme$, tha
 SP_JOBOWNPAL -1, tha + 4
..
Now it might be argued that the extra ID is an unnecessary security feature. After all we already have the extension, _thb, and know the expected file size, SP_GETCOUNT x 2. Also you wont crash the computer if you happen to have a thb file with 114 bytes of nonsense.. Besides, so many other formats in QL land dont have any ID (sprites, screens, etc).

We thought it was a good idea to have the extras ID, but now I waiver..

Any views on this?


Per
dont be happy. worry
- ?
RWAP
RWAP Master
Posts: 2833
Joined: Sun Nov 28, 2010 4:51 pm
Location: Stone, United Kingdom
Contact:

Re: Theme file format

Post by RWAP »

A good idea - I like the idea of an identifier at the start however, so that it would be possible to load a single theme file format with several sets of palettes if necessary - eg to have a different system palette for a secondary program running within the main one; or maybe to allow a different system palette dependent on whether text or icons are being displayed to control a program....


User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Theme file format

Post by NormanDunbar »

I agree, the flag and version word makes sense, especially as it could happen that progress takes us on to new versions of wman etc with a different number of words required for a theme. Unlikely, I admit, but still possible. We could increment the version then to ensure, along with flen, that we are loading a correct theme.

Cheers,
Nirm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Theme file format

Post by pjw »

Rich suggests the following improvement, with which I concur:

dc.w 'TH' ; identifier
dc.b 1 ; version number
dc.b 57 ; number of word entries in the table
dc.w $200
etc...

Should be good until the turn of the century..


Per
dont be happy. worry
- ?
User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Theme file format

Post by pjw »

I know some people must find this incredibly unimportant and boring, but Im on the cusp of having to commit, so I need to be sure that Ive made a future-proof choice. I know, we could just go to one of our Oracles for a "best answer", but that would be a cop out. Anyway, Ive been thinking some more, and Ive come up with the following suggestion:

header
dc.b "THB", 57

data
dc.w $0400
dc.w $FFFF
..

The reasoning is as follows: The header is only required so we know we have the correct file type and that the data is likely to conform with what we expect. If WMAN2 were expanded to use a palette of say 58 items, the new value of SP_GETCOUNT would warn us that the file was the wrong version.

If for any reason, in the future, it would be necessary to indicate that a completely new and incompatible version was in effect, it would be simple enough to adopt a new header for the format, say:

dc.b "THC", xxx

If the THC format also turned out to have 57 entries we'd be fcuked, of course, but using the version number of n wouldnt have helped either. So to my mind, THB, 57 is just simpler and cleaner, without any adverse effect on the integrity of the format.

Unless there are any objections within the next 7 days, this will be what I commit to.


Per
dont be happy. worry
- ?
User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Theme file format

Post by pjw »

Ok, after all the fuss, Im inclined to go with a header-less binary file after all. That is, currently, 57 * 2 = 114 bytes of palette information in the same order as that currently used by Wman2 (and _thm files as used by QCoCo). The order is unlikely to change, and should the number of items change, the length of the file will give the game away. Where the wrong file to be loaded, no calamity will ensue, provided the programmer reserves sufficient memory, ie: memory >= size of the actual file (rather than the expected size of the file). With this announcement, I wish to claim the thb extension for this purpose and format!

Thanks to all for your input. It helped clarify the issue.

PS: ModView is a minor utility by me that uses this format. It simply lists all the modules contained in an SMSQ/E binary. ModView06_zip is available from Dilwyn's at http://www.dilwyn.me.uk/utils/index.html.


Per
dont be happy. worry
- ?
Post Reply