SpriteOp help?

This is embarrassing, it seems I’m confident enough to try to re-write a large chunk of RISC OS, but not smart enough to even use it! Can someone fix this little program, so that I don’t get a 5×34 image on the screen but the full 34×34? (On the plus side, it’s nearly equally bad on both the real thing and my experimental kernel!)

SYS"OS_File", 17, "Resources:$.Resources.Wimp.Sprites" TO ,,,,L%
DIM S% L%+4
SYS"OS_File", 16, "Resources:$.Resources.Wimp.Sprites", S%+4, 0
!S%=L%
SYS"OS_SpriteOp", &122, S%, "file_ffe", 1000, 1000, 0

Use Plot Sprite Scaled – reason code 52. The Wimp Sprites are unlikely to be in the same pixel format as the screen. That one is defined in MODE 15, so 256 colours and non-square pixels.

You could avoid going via ColourTrans by setting bit 4 of the flags word for OS_SpriteOp &100+52.

And quickly avoid scaling factors by loading the Sprites22 file, not Sprites.

Thanks, I’ll give it a try. The Sprites (without 22) is a Sprite file in Resources that hasn’t been squashed.

You do not need to go to the Resources file, because it is a Wimp sprite:

SYS"Wimp_SpriteOp",52,,"file_ffe",1000,1000,16

If you do want the Resources file you can use it directly without loading it:

file%=OPENIN"Resources:$.Resources.Wimp.Sprites22"
SYS"OS_FSControl",21,file% TO ,area%
CLOSE#file%
SYS"OS_SpriteOp",52+256,area%-4,"file_ffe",1000,1000,16

Edit: Just to add that RFSFiles will also give you the area:

SYS"RFS_Data","Resources.Wimp.Sprites22" TO ,area%
SYS"OS_SpriteOp",52+256,area%,"file_ffe",1000,1000,16

That’d be great, except I need SpriteOp working to get the Wimp to initialise!

That OS_FSControl hint is very useful, I had a feeling there was a way to find that, but I couldn’t find it. Is there documentation on RFS_Data? Is it a separate module?

From Simon Willcocks:

SYS"OS_File", 17, "Resources:$.Resources.Wimp.Sprites" TO ,,,,L%
DIM S% L%+4
SYS"OS_File", 16, "Resources:$.Resources.Wimp.Sprites", S%+4, 0
!S%=L%
SYS"OS_SpriteOp", &122, S%, "file_ffe", 1000, 1000, 0

That’s not how you should load a sprite file. Use OS_SpriteOp to load the file. Then the OS can validate the file is actually a sprite file before you try doing anything on it.

From Steve Drain:

If you do want the Resources file you can use it directly without loading it:

No you can’t because Resources: doesn’t necessarily reference ResourceFS. You can use that as a fallback, but no code should ever rely on it being in ResourceFS.

RFSFiles is my own module, so not suitable for your work, I think. ;-)

The OS_FSControl method is taken from, say, Resources.$.Resources.Alarm.!RunLink, where it has probably been used since RISC OS 2. It does rely on the way ResourceFS works as a filing system. The address is adjusted to point to the size word of the RFS sprites file, so that it acts as a sprites area.

Edit: In the light of Charles’ comment, you should, perhaps, use the full protocol of the Alarm.!RunLink example. ;-)

That’s not how you should load a sprite file. Use OS_SpriteOp to load the file. Then the OS can validate the file is actually a sprite file before you try doing anything on it.

OK, but I’d still have to read the file size, and create a sprite area to accommodate it, wouldn’t I? Is that any safer?

OK, but I’d still have to read the file size, and create a sprite area to accommodate it, wouldn’t I? Is that any safer?

Yes, you still read the file size and create the sprite area – that’s the right way to load a sprite file.

What I’m saying is that using OS_SpriteOp 10 (Load sprite file) ensures that the OS has an opportunity to validate the sprite file when it’s loaded – you are safer doing it that way, and you shouldn’t really just load it into memory directly, because the OS gets no opportunity to check that for you.

Edit: In the light of Charles’ comment, you should, perhaps, use the full protocol of the Alarm.!RunLink example. ;-)

Just for reference, if you do it with just the code pasted on Pyromaniac using Resources$Path, you get:

{long python backtrace, including...}
  File '<main>/riscos/graphics/spritearea.py', line 996, in riscos.graphics.spritearea.SpriteArea.__init__
    address = 16056316    0xf4fffc
      994 :     def __init__(self, ro, address):
      995 :         super(SpriteArea, self).__init__(ro, address, 0)
      996->         self.size = self.word
...
{more snipped}
ROMemoryReadError: Read of &00f4fffc failed (read word)
  Exception properties:
    abort_type = "read"
    address    = 16056316    0xf4fffc
    pc         = None
  r0  = &00000134, r1  = &00f4fffc, r2  = &00107fc8, r3  = &000003e8
  r4  = &000003e8, r5  = &00000010, r6  = &00000000, r7  = &00000000
  r8  = &00000000, r9  = &00000000, r10 = &0000000d, r11 = &000086d8
  r12 = &00008faf, sp  = &04107fe0, lr  = &04107f84, pc  = &000086dc
  CPSR= &60000013 : SVC-32 ARM fi ae qvCZn
  SPSR= &20000013 : SVC-32 ARM fi ae qvCzn
Exception: Data abort
  r0  = &00000134, r1  = &00f4fffc, r2  = &00107fc8, r3  = &000003e8
  r4  = &000003e8, r5  = &00000010, r6  = &00000000, r7  = &00000000
  r8  = &00000000, r9  = &00000000, r10 = &0000000d, r11 = &000086d8
  r12 = &00008faf, sp  = &04107fe0, lr  = &04107f84, pc  = &000086dc
  CPSR= &60000013 : SVC-32 ARM fi ae qvCZn
Error: Internal error: Abort on data transfer at &000086dc (DA 'Application Space') (read at &00f4fffc) (Error number &80000002)

Because the native filesystem returns an fshandle of &f50000 which increments on each open file – that’s just its internal implementation so that it generates some identifiers that are a bit weird and might provoke odd behaviour.

I presume the Alarm ‘!RunLink’ thing you mentioned explicitly checks for the filesystem in the FSInfo word being ResourceFS before acting on it, and then falls back to regular loading from disc? Oh dear.

10REM > !RunLink
20H% = OPENIN("Alarm:!RunImage")
30IFH%=0 ERROR 0, "!Alarm RunImage cannot be found"
40SYS "OS_FSControl",21,H% TO ,A%,W%
50CLOSE#H%
60IF (W% AND &FF)=46 THEN PAGE=A%:RUN
70ERROR 0, "!Alarm cannot run in RAM"

Yeah, don’t use that as an example of how to load things from resources, except how to identify it isn’t in resources before falling back to regular operations.

Genuinely unsure why I didn’t rip !Alarm out of ROM.

Yes, you still read the file size and create the sprite area – that’s the right way to load a sprite file.

OK. Example code?

Genuinely unsure why I didn’t rip !Alarm out of ROM.

And drop in the bin?

Example code?

Something like this, presumably:

REM Load a sprite file into a new block of memory, claimed via DIM.
REM
REM \param file_name$		The filename of the file to load.
REM \return			Pointer to new sprite area, or 0 on error.
:
DEF FNload_user_sprites(file_name$)
LOCAL area%, size%, type%

SYS "OS_File", 17, file_name$ TO type%,,,,size%

IF type% = 1 THEN
	size% += 4
	DIM area% size%
	!area% = size%
	area%!8 = 16
	SYS "OS_SpriteOp", &10A, area%, file_name$
ELSE
	area% = 0
ENDIF

=area%

There’s a more complete version, with support for Wimp sprite suffixes, over on GitHub.

OK. Example code?

See PRM chapter on Sprites, section ‘Technical details’, subsection ‘Memory operations’. Specifics of OS_SpriteOp 9 are linked to from there, in the section SWIs, swi definition for OS_SpriteOp 9. Specifics of loading sprite files described in the section ‘File operations’, with detail linked to from that section for OS_SpriteOp 10.

Example code which does this and plots in many different forms:

https://github.com/gerph/riscos-examples/blob/master/graphics/sprites/PlotSprite%2Cfd1

There’s a more complete version, with support for Wimp sprite suffixes, over on GitHub.

The handling of the wimp sprite suffix that you have should be used as a fallback, with Wimp_Extend 257 being used to obtain the actual suffix to use.

Documented API:

=> R0 = 257
   R1 = pointer to filename in a buffer to be updated
<= R0 = pointer to buffer passed in
   R1 = 0 (if buffer updated, preserved if not supported by this Wimp)

This SWI is used to append a mode suffix to a filename within a buffer. The
buffer should have space for up to 8 characters in addition to the filename
in order to allow for future expansion. The suffixes follow the standard
pattern of describing the pixel sizes in terms of OS units (see
Wimp_ReadSysInfo 2 in PRM 3-218).

Initially, the current mode suffix will be tried. If this does not exist,
the name will be normalised to the lowest pixel size. If the suffix is 11
and this fails then 22 will be tried. If these fail, then the call will fall
back to no suffix. For example, in a mode with pixels using the size 1 OS
unit in the x direction and 4 OS units in the y direction (eigen factors EX0
EY2) the suffixes examined would be 14, 24, 44 and finally falling back to
no suffix.

Clients should check whether R1 has been set to 0 on return. If it has not,
this call is not supported by the WindowManager.

Note: Under Select 3i1 this call was Wimp_Extend 14 but this was found to
clash with an undocumented call under RISC OS 5. It has been
reallocated.

Genuinely unsure why I didn’t rip !Alarm out of ROM.

And drop in the bin?

Yeah, it’s really not a great app :-(

!Alarm, or at least a calendaring app, was due to be replaced in the time frame of Select 6, as the prototypes that were being worked on in the timeframe of Select 4 would need more time to gestate and improvements to the Toolbox to make it functional.

There was no reason for Alarm to be in ROM, and like Paint and Draw before it, it would have been sensible to remove. It’s possible that by the time I’d removed the others the pressure for ROM space had been completely alleviated.

The handling of the wimp sprite suffix that you have should be used as a fallback, with Wimp_Extend 257 being used to obtain the actual suffix to use.

Good spot… It looks as if I do it (more) properly in my C library, but the BASIC version presumably pre-dates my having read the documentation. I suppose I’d better update it at some point. :-)

Alpha masks aside, is there any reason for not using Wimp_ReadSysInfo 2? My C version of the routine uses that, and I’ve a hazy memory that it’s because I can assemble the filename in a bounds-checked snprintf() buffer and not rely on Wimp_Extend 257 staying within the space allocated (Wimp_Extend 13 has that option, but it’s RO5 only).

… not rely on Wimp_Extend 257 staying within the space allocated

Why wouldn’t you rely on that? It is explicitly documented how much space is required, so there is no need to request how much space you will need.

The buffer should have space for up to 8 characters in addition to the filename in order to allow for future expansion.

Wimp_Extend 13 is explicitly in the region which clashes, so shouldn’t be used. The clash is precisely the reason that the values up at 256-258 exist, so that people don’t use the clashing versions which will break if they’re used on the different systems. Castle were informed of the clash and the use of different values, and the documentation which had been released updated to reflect the clash. They did not respond.

I presume from your comment (And the documentation on the RISC OS open site) that they ignored this and continued using the clashing values. It is unsafe to use Wimp_Extend 13 unless you explicitly check the operating system you are running on – a wholely unacceptable state of affairs.

Why wouldn’t you rely on that? It is explicitly documented how much space is required, so there is no need to request how much space you will need.

The documentation that I’m looking at only says that

it’s recommended that there’s enough spare space for at least 8 extra
characters to be inserted

which doesn’t sound that certain about the fact. I’m not sure that I would like to rely on a “recommendation” that I leave space for “at least” n extra characters; I’d prefer a guarantee that the call “will never append more than n characters” to the supplied buffer, because that’s something that we can work with.

Having done some digging, it seems that

The buffer should have space for up to 8 characters in addition to
the filename in order to allow for future expansion.

comes from the printed RISCOS Ltd PRM, which is only available to a select few¹ and isn’t actually that much more definite on the matter in hand than the ROOL Wiki version. I can see no mention of the matter in the RO6 PRM, either.

Wimp_Extend 13 is explicitly in the region which clashes, so shouldn’t be used.

I’ve not seen this documented anywhere? I was peripherally aware of a clash somewhere, but it isn’t explicitly mentioned in the ROOL Wiki PRM, and isn’t mentioned at all in the printed RISCOS Ltd PRM, despite the latter documenting both 13 and 257 on almost adjacent pages. In fact, the only documentation which does hint at this is the ROOL Wiki PRM, which says of 257:

Compared to Wimp_Extend (sprite suffix), this call has the advantage
that it is available in both the RISC OS Open and RISC OS Select versions
of the Wimp, easing the task of writing software which is compatible with
both OS versions. However unlike the RISC OS Open version of the call, no
buffer size is specified, and so buffer overruns are possible.

Based on this, not to mention my own views on assuming buffer lengths, Wimp_Extend 257 appears to be more widely available² but have a less desirable API – although you’re saying that it’s defined elsewhere³ precisely how long the buffer needs to be. This doesn’t seem to be too clever: it’s exactly the kind of thing that Acorn did with Wimp_Poll in 1987, and which led to the messy hack with Wimp_GetWindowInfo which we all know and love.

I presume from your comment (And the documentation on the RISC OS open site) that they ignored this and continued using the clashing values. It is unsafe to use Wimp_Extend 13 unless you explicitly check the operating system you are running on – a wholely unacceptable state of affairs.

I think you might be assuming rather a lot, and possibly letting your own prejudices show.

Having looked at both the ROOL Wiki PRM and the printed RISCOS Ltd PRM, it’s only the ROOL one which even suggests that using Wimp_Extend 13 might not be a good idea (see the quote above); the RISCOS Ltd PRM documents both calls, and makes no mention that I can see of why one might be better than the other. In fact, given that 13 allows the buffer size to be queried and defined, it looks on paper to be the better call to use. Since the RISCOS Ltd PRM documents 257, presumably the issue with duplicate reason codes was known about at the time when it was printed – so why not document the problem and make it clear to readers that 13 is included just there for completeness?

The very fact that you’re quoting apparently secret documentation at me is exactly why this kind of thing happens. Is any of this actually documented properly anywhere that us mere mortals have access to, or is it all in secret RISCOS Ltd documents that we’re not allowed to see⁴?

So, setting the politics aside, can I re-ask my question: alpha masks aside, is there any reason for not using Wimp_ReadSysInfo 2? It’s available back to RISC OS 3.1 without any need for OS version checks or fall-backs, and the only documented limitation that I can find is that it won’t support alpha-mask suffixes. If we know that our applications don’t use those, does this matter? Are there any other side effects?

¹ What was the print run, and how many of those are left within the reach of active developers?

² But it’s still not available pre-RISC OS 4.37, which isn’t that useful if we’re supporting systems back to 4.02, or 3.5, or even 3.1.

³ Through private knowledge of the implementation?

⁴ Back in 2002 I used the Filer Action Plugin documentation that was sent out on a Select Subscribers’ CD to add functionality to Locate 0.65. For my efforts, I received an unsolicited email from RISCOS Ltd which noted that they gathered that I had been “passed on a copy of the FilerAction document”, with the author continuing that “since it’s not on public Select site release yet, I’d rather you had confirmed it with me directly”, because there were “condition[s] of having the pre-release documents”. It all went a bit surreal after I replied to point out that it had been “passed” to me by RISCOS Ltd themselves on the last Select CD: the author came back to me, stating that “the documentation issued is way out of date”, and then appeared to go on to accuse (by name) several folk at RISCOS Ltd for releasing stuff to users without his permission.

which doesn’t sound that certain about the fact. I’m not sure that I would like to rely on a “recommendation” that I leave space for “at least” n exctra characters; I’d prefer a guarantee that the call “will never append more than n characters” to the supplied buffer, because that’s something that we can work with.

Ok, I didn’t state it strongly enough when I wrote the documentation. It will not write any more than that. Mea culpa.

However unlike the RISC OS Open version of the call, no buffer size is specified, and so buffer overruns are possible.

No buffer overrun is possible if you follow the documentation.

Wimp_Extend 13 is explicitly in the region which clashes, so shouldn’t be used.

I’ve not seen this documented anywhere?

That would almost certainly be because – as I implied – Castle did not care about any form of compatibility, even when informed of the fact, so the documentation you’re going by doesn’t care to note such things. But it is documented within the WindowManager documentation, in exactly the form I just cited:

http://www.riscos.com/support/developers/riscos6/desktop/wimp/wimpcnp.html

Based on this, not to mention my own views on assuming buffer lengths, Wimp_Extend 257 appears to be more widely available2 but have a less desirable API – although you’re saying that it’s defined elsewhere3 precisely how long the buffer needs to be. This doesn’t seem to be too clever

Dear god I sound like a real dick. I can only appologise for that. Sorry. :-(

< “Uncle Albert” mode > “During The War” – people did many things. </>

We’re all more sensible now. People keep fixing things in the OS and updating the wiki documentation (which flows through into the official-for-printing version)

That would almost certainly be because – as I implied – Castle did not care about any form of compatibility, even when informed of the fact, so the documentation you’re going by doesn’t care to note such things.

The documentation that I’m “going by” is community documentation, contributed by those using RISC OS 5. AFAIK it isn’t Castle documentation, and isn’t even on a Castle website.

But it is documented within the WindowManager documentation, in exactly the form I just cited:

First, it’s on a page titled “WindowManager ‘Cut and Paste’”, which isn’t an intuitive place to look… Second, it’s still assuming knowledge that I don’t have.

The RO6 PRM says of Wimp_Extend 257:

Under Select 3i1 this call was Wimp_Extend 14 but this was found to
clash with an undocumented call under RISC OS 5. It has been reallocated.

It states that it was reason code 14 which clashed, not 13, and there’s no mention of 13 clashing. At the same time, the printed PRM from the same stable documents both 13 and and 257 as being equivalent functions with different APIs and platform availability, but makes no mention of any clash of reason codes.

I’m not doubting you here; just highlighting that this information is still largely undocumented folklore. Where does the documentation state that we shouldn’t be using reason code 13 because it means different things on different systems? It’s not mentioned at all in the RO6 PRM as far as I can see, and both the printed ROL PRM and the ROOL Wiki document 13 and 257 as being valid and safe ways to complete a sprite file name (or, they don’t say that either is not safe).

Would it be too much to ask for someone to update the ROOL Wiki to detail definitively which reason codes are safe to use, and which have differing functions on different systems? It’s not a Castle site, so they’re not going to be involved.

it was documented at the time what the recommendation for size was (which if you’re an engineer, you use the recommendations unless you have good reason not to, same with any other documentation).

Kind of. On a platform with a known history of API brokenness WRT buffer sizes dating back to 1987, opting for a call where buffer sizes can be explicitly stated – if one is available, and there are no down-sides – feels better.

Also, having been an engineer (of a hardware persuasion, mostly) for a couple of decades, I’m all too well aware that non-explicit recommendations in data sheets often tend to be non-explicit for very good reasons. :-)

This is not a secret document – I don’t know where you get the idea that I’m citing some arcane or private information. It was documented explicitly at the time of RISC OS Select release. Which is to say that it’s been public information for the last 15 years.

The problem with the Select documentation was that it was just for subscribers, and even then (as my anecdote highlighted) it was far from clear whether developers could use the documentation supplied on the CDs or website. That, and the fact that by the time all of these clashes were happening, many of us had decided to stop throwing good money after bad and had withdrawn from the scheme – and so would not have had access to the information anyway.

Unless I’m mistaken, the RO6 PRM has never been a full set of the documentation from the Select days? With the Select website gone and CDs unreadable (mine were, when I went to archive them a few years back), much of the documentation appears to be lost.

So, setting the politics aside, can I re-ask my question: alpha masks aside, is there any reason for not using Wimp_ReadSysInfo 2?

It only gives you a single suffix and you have to do the necessary fallbacks yourself. That’s really the only thing that is restrictive. So it’s still an entirely reasonable thing to do, if you accept that changes to the OS won’t be picked up by your code.

Thanks. I’ll need to update the BASIC library, so I’ll look at updating both that and the C one to use one of the newer OS APIs in preference.

It’s also referenced in my C tutorial, so it would be useful to update that, too. If there’s a politics-free, definitive explanation of which Wimp_Extend reason codes are ‘safe’, I’ll attempt to summarise that in the explanation. I think I’m clear that WE 14 became WE 257 and so 14 is obsolete; what I’m not clear on is whether there are also two uses for WE 13 on RO4.x and RO5.x respectively, which makes the use of WE 13 dangerous as well. I can find no mention of what Select used WE 13 for (although the ROL docs refer to the RO5 usage, which implies that Select didn’t use it for anything else), while RO5 obviously used it for sprite names?

What was the print run, and how many of those are left within the reach of active developers?

Sorry, not a clue; that was after my time.

It was a rhetorical question. My point was that piecing together how to use any RISC OS API added after about 1995 seems to be almost impossible. Documentation, where available, is spread amongst Acorn App Notes, Select documentation (which may not be available any more), the Iyonix website (which only lives on in the Web Archive), 3QD’s site (which is RO6, but seems to be missing “older” stuff), the ROOL Wiki (which is RO5-centric, community-led and incomplete) and the StrongHelp manuals (which are unofficial, incomplete and often out of date).

There’s been talk of projects to bring this all together, but for now they’re just vapourware.

Dear god I sound like a real dick.

To be clear, it wasn’t you – in fact, you were one of those named in the final email that I received as being guilty of smuggling illicit documentation out of ROL, into the hands of the undeserving developers.

I’d considered noting that you were one of those being blamed for the “leak” in my original post, but thought it better to leave all names out of the anecdote; that probably only served to make it ambiguous, for which apologies.

… and a belated “thank you” for providing the allegedly dodgy Filer Action Plugin documents all those years ago. :-)

I can find no mention of what Select used WE 13 for (although the ROL docs refer to the RO5 usage, which implies that Select didn’t use it for anything else), while RO5 obviously used it for sprite names?

I have here printed copies of the ROL Window Manager PRM, and the Acorn PRM Vol 5a.

The Acorn manual is terse – “Wimp_Extend” This call is for internal use only , you must not use it in your own code."

The ROL PRM has pages for Wimp_Extend 13, 256, 257 and 258. (Nothing for 14!)
I could scan the pages if that would be useful.
Briefly,

on entry R0=13 (reason code), 

R1=pointer to pathname of file without suffix

R2=pointer to buffer for result

R3 is size of buffer, or 0 to read buffer size required.

On Exit, R0 corrupted, R1-2 preserved. R3=space left in buffer, or size of buffer*-1 if R3=0 on entry.

Head above the parapet…

Discussing the past and how we got here, is undoubtedly interesting, but it doesn’t take us forward. Various sources of information are cited. One stands out in particular: the ROOL wiki, as it is:

• the only one that can be freely updated,
• it’s freely available to everybody,
• it is particularly for the only living branch, but can certainly document calls that are risky to use – and can recommend people not to use them. An informal deprecation.

So: is/are any of you willing to update the ROOL wiki?

Although I have updated the wiki in the past, there’s no point in my volunteering for this topic, since I don’t use these calls – I have no working knowledge of them, I’d be merely parroting what someone else said.

AFAICS this would take us forward.

First, it’s on a page titled “WindowManager ‘Cut and Paste’”, which isn’t an intuitive place to look… Second, it’s still assuming knowledge that I don’t have.

Yeah, that’s a bloody stupid place for it to be in.
It was originally in a document called WimpExtend257.txt.
The full text of that document as I have it is as I quoted above, so there’s nothing more to note there.

The reason for it being there… well, whoever it was that turned my text into the HTML (I’m pretty sure it wasn’t my conversion that was used but… dunno, I can’t remember) put the two together. And then when I reviewed the docs before publication, it was missed :-( Sigh. But still… documented.

The RO6 PRM says of Wimp_Extend 257:

Under Select 3i1 this call was Wimp_Extend 14 but this was found to
clash with an undocumented call under RISC OS 5. It has been reallocated.

Yes, that’s pretty much what the documentation I have said.

It states that it was reason code 14 which clashed, not 13, and there’s no mention of 13 clashing. At the same time, the printed PRM from the same stable documents both 13 and and 257 as being equivalent functions with different APIs and platform availability, but makes no mention of any clash of reason codes.

That is correct. ROL Wimp_Extend 14 clashed with something. It was unknown what it was at that time because Castle hadn’t documented anything, and had not responded to the report. The only thing that was known was that it caused some Castle software to crash.

13, by implication must have clashed, because it was added between the time that the OSs diverged. However, 13 had never been documented in Select, so the only things that should have been using it were the internal RISC OS APIs, so it wouldn’t have needed any further documentation. The only user of it was the Filer, and as that was part of the OS that was delivered, it was reasonably safe.

Really it should have been noted that both were dangerous, but hindsight is a wonderful thing.

Documentation from the commit history:

commit e842deba590cb6e8588430c311de6414e55b756f
Author: justin <>
Date:   Mon Jul 14 23:01:55 2003 +0000

    Summary:
      Moved all new Wimp_Extend calls to avoid Castle's undocumented calls.
    Detail:
      * Castle have supplied some software which uses undocumented Wimp_Extend
        calls. The likelihood of them moving them is just about zero, so I'm
        moving all our calls to a separate block. (sigh).
      * We now export headers that describe the ReadSysInfo and Extend reasons
        so that we can use those instead.
    Admin:
      Tested on build machine and still works, but will require new builds of
      SciCalc, ResEd, XChars, DragASprite, Filer, RISC_OSLib, ConvertGIF,
      and Toolbox.
    Tag:
      Wimp-5_12

Again, those applications should all have been ok as they were using the 14 call, not the 13 call.

The two calls which are problematic are 13 and 14. From the code for the original implementation,
and including the prior call for reference:

  [ NCErrorBox
;   12= Suspend pointer temporarily (for error boxes)
  ]
  [ PrioritySpritePool
;   13= get sprite address
;       => R1 = sprite area to use (0, 1 or area)
;          R2-> sprite name
;       <= R1-> sprite area
;          R2-> sprite
  ]
;   14= get suffix specific filename
;       => R1-> filename in a writeable buffer
;               (+8 space for 8 characters)
;       Filename updated to contain a filename with suffix appended

Call 13 is required for anyone wishing to emulate the behaviour of the Wimp’s sprite pool lookups
for the area numbers and obtain the area as well as the sprite (IIRC).

The interface change in 5.12 was to move 13 and 14 to 256 and 257.

Essentially all the other low numbers were now unknowns and it was completely impossible to use them in Select because they were not documented and we didn’t know how far they’d gone in allocating numbers.

For reference 258 is documented on the same page: http://www.riscos.com/support/developers/riscos6/desktop/wimp/wimpcnp.html and describes how you read the colourmap descriptor which the Wimp will use. This is necessary for any client wishing to emulate the Wimp’s selection mechanism.

I’m not doubting you here; just highlighting that this information is still largely undocumented folklore. Where does the documentation state that we shouldn’t be using reason code 13 because it means different things on different systems? It’s not mentioned at all in the RO6 PRM as far as I can see.

I suspect that was because it was entirely internal, and there was no need to document it. ROL was not in the business of documenting the APIs used by Castle – that was Castle’s problem – as I had enough to do documenting what was there and making sure that there weren’t other problems. I could move out of the way and there would be no issue. Why not document that it shouldn’t be used? One reason was that I was not prepared to start pointing fingers with ’you’ve done this wrong’. The correct means by which such dirty laundry should be dealt with is by communicating the problems and having it dealt with out of public sight. And if they were unwilling to do that, we can avoid any appearance of there being issues by moving out of the way and documenting where necessary.

I genuinely don’t understand why the ROL PRM has any mention of 13, other than to say never to
use it. As for the ROOL Wiki, now you know and you can document it properly.

Would it be too much to ask for someone to update the ROOL Wiki to detail definitively which reason codes are safe to use, and which have differing functions on different systems? It’s not a Castle site, so they’re not going to be involved.

You have the information go to it! It’s only a little more than the information that was previously released, so anyone could have done this in the past.

As for it not being a Castle site, that’s true, but as evidenced by the wiki and by the OS itself, there is a general disregard for compatibility and acknowledgement of Select in general which persists. Yeah, bitter. Sigh.

Also, having been an engineer (of a hardware persuasion, mostly) for a couple of decades, I’m all too well aware that non-explicit recommendations in data sheets often tend to be non-explicit for very good reasons. :-)

That’s when they’re written by people that choose their words carefully. I admit this was not one of those cases :-(

The problem with the Select documentation was that it was just for subscribers.

All the Select 3 documentation was public. I finally won that battle at that point, and it was a hard fought thing at times. I really wanted all the documentation and the SDKs to be public, because then people know how to use them, and can see the benefits of the system.

Unless I’m mistaken, the RO6 PRM has never been a full set of the documentation from the Select days? With the Select website gone and CDs unreadable (mine were, when I went to archive them a few years back), much of the documentation appears to be lost.

I have lost a lot of things over the years. Text files and some references to the releases still exist for me – and of course the documentation for S3 is on the web too.

Why doesn’t stuff exist on archive.org, I hear you cry? Because all the pages on the ROL site were marked as not being archivable. Why would you do that, I hear between the sobs of disbelief? Because Castle had threatened legal action against some of the documents on there and the Printers release, and had followed that up by demanding that historic evidence be removed as well so that it could not be found. In the face of that insert terms of your choice there behaviour, we decided to just remove the possibility of them complaining and having to go through that process again should they decide that something else that had been agreed could not be published.

Sorry, yes, I’m bitter about these things, but it’s a bitterness about actual events and actions by those involved.

There’s been talk of projects to bring this all together, but for now they’re just vapourware.

I’m sure that someone talked about this in great detail recently…

If you want to be involved in work in that area, just say the word.

Dear god I sound like a real dick.

To be clear, it wasn’t you – in fact, you were one of those named in the final email that I received as being guilty of smuggling illicit documentation out of ROL, into the hands of the undeserving developers. I’d considered noting that you were one of those being blamed for the “leak” in my original post, but thought it better to leave all names out of the anecdote; that probably only served to make it ambiguous, for which apologies.

Ah the illicit docs trade… Your first API is free, after that you have to pay? :-D

It could quite easily have been me – I know I acted badly too at times – although I did think it would be odd as I /thought/ that I’d always argued for free docs. My memory sucks and I… well, I’m regularly told that I feel guilt for things that are not my fault. But sometimes they are my fault!

Apology unnecessary, but thank you in any case.

… and a belated “thank you” for providing the allegedly dodgy Filer Action Plugin documents all those years ago. :-)

You’re welcome. At least hopefully this has explained some of this huge aside from the sprite operations.