TTXHelper module |
Refer to the copy of the documentation (below) for further details...
Software name : TTXHelper Latest version : 0.02 Archive size : 63430 bytes Classification : Freeware Registration cost : None RISC OS 2 compatible : Unknown RISC OS 3 compatible : Yes WIMP 3.98 compatible : Yes RISC OS 4 compatible : Untested, should work okay 32bit RISC OS : Yes Written in : Assembler Libraries : n/a
PtrIIC download | ||
th002.zip (62K) |
Version 0.02 2004/02/17 | The TTXHelper module, and documentation, v0.02. |
TTXHelper v0.02 ================ Introduction ------------ The TTXHelper module provides various 'additional' facilities for use with the !Teletext system. It works in conjunction with the Teletext+ module (by Colin Granville) as used by my !Teletext and Paul Skirrow's !Teletext+. This module does NOT replace Colin's Teletext driver module. If you wish to copy for anybody other than yourself, distribute, or include this module with any programs other than my !Teletext; please read the "Licence". Compatibility (teletext hardware) ------------- TTXHelper is compatible with the Ground Control receiver. It SHOULD be compatible with other devices that use the standard IIC EuroCCT/CITAC/VIP2 arrangement - in which case it will report your receiver as being compatible with the Ground Control UTA-3. "Results may vary". TTXHelper has 'provisional' support for the RiscTV teletext system, but this has not been tested as I do not have the necessary hardware. The auto-detection will try RiscTV if nothing else is found. Note that this MAY cause your computer to freeze. It shouldn't, but I figured I'd better add a disclaimer because I'm coding for something I don't have... TTXHelper can be set to use teletext hardware connected to the parallel port via my "PtrIIC" module. The auto-detection routines take this into account. This has been tested with my receiver and PtrIIC v0.04. IMPORTANT! If you have a teletext receiver for RISC OS that you would like me to support (either if you have one spare, or if you make them and don't object to sending me one), then I'll be more than happy to modify my code to support it if you can post it to me. I have written teletext software for DOS that fakes IIC (also in the PtrIIC module), so I am au fait with talking to IIC devices, so if your hardware does when the Ground Control unit does, but in a slightly different way (so much so that the Teletext driver module doesn't work), please contact me with further details. Compatibility (RISC OS) ------------- This module has been written to be 26/32 bit neutral. It flags itself as being 32bit aware, so should run natively on an Iyonix. SWIs ---- This module uses SWI chunk &57180 which was allocated to myself, Rick Murray, for "TTXHelper" on the 16th of February 2004. You may refer to these SWIs by name or by number, as they may be added to but they're unlikely to change. The errors that may be returned are offset within the error block allocated to my PtrIIC module. As each block contains 256 error codes, I forsee this being shared among a number of modules. Therefore, the following error codes are reserved for TTXHelper: &81B510 - 81B52F (31 error codes). Registers not explicitly noted as returning a value or otherwise being corrupted will be preserved and restored upon exit from the SWI. This module is designed to be 26/32 neutral, so no attempt is made to preserve the processor status register. It is thus likely that flags WILL be corrupted. TTXHelper_AutoDetect &57180 Entry: - Exit: R0 = -1 if no teletext hardware located 0 if teletext hardware not recognised 1 if Ground Control (UTA-1) or compatible 2 if Ground Control (UTA-2) of compatible (not supported) 3 if Ground Control (UTA-3) or compatible Other values reserved. R1 = If R0 is 0-2, then this register will be valid: 0 if connection is via system IIC bus 1 if connection is via PtrIIC module 2 if connection is via RiscTV's IIC Other values reserved. R2 = Bytes of on-board memory detected, or -1 if not tested. R3 = Reserved; returns module version *100 (i.e. 101 is v1.01). Side effects: This corrupts a few bytes within the memory of the teletext receiver. This call attempts to detect what kind of teletext hardware is connected, and to which IIC implementation it is connected. The UTA-2 version will never be returned as I do not have access to one to tell the difference between it and the other models. IMPORTANT! This detection does NOT alter the behaviour of the TTXHelper module. Once you are satisfied that the device returned is correct, call TTXHelper_UseInterface to set the desired interface. IMPORTANT: This has, so far, only been tested with a UTA-3 type receiver attached via the system IIC bus, with no receiver attached, and with PtrIIC loaded but no receiver attached (at all). TTXHelper_ScanFlash &57181 Entry: R0 = Pointer to 'source' frame. R1 = Pointer to 'destination' frame. Exit: R0 = 0 if no flash commands encountered, else a count of 'flash on' codes scanned. This call will read a 1040 byte frame from 'source' and copy it into the 'destination' block. As it does so, any "flashing" content will be replaced with spaces, thus you may then create the illusion of flashing by simply switching which frame is displayed. I find a pleasing flash rate is ~75 centiseconds, equal on/off times. The EuroCCT provides a 75% duty cycle signal with a period of 1.28 seconds (driven from the 40ms/25Hz frame rate output); so it is on 3/4 of the time and off 1/4 of the time; the entire time lasting slightly over a second and a quarter. TTXHelper_ConvertToISO &57182 Entry: R0 = Pointer to 'source' frame. R1 = Pointer to 'destination' frame. R2 = Language (0 = GB; 1 = F; 2 = S; 4 = D; 5 = E; 6 = I) Exit: - This call will copy the frame. In the process, ALL graphics will be converted to spaces (ie, removed) and all possible characters will be converted to their ISO 8859/1 (Latin1) equivalent, paying attention to the language identification of the page. This is intended for save/export routines. TTXHelper_ConvertToANSI &57183 ** NOT IMPLEMENTED ** Entry: R0 = Pointer to 'source' frame. R1 = Pointer to 'destination' frame. R2 = Language (0 = GB; 1 = F; 2 = S; 4 = D; 5 = E; 6 = I) ** NOT IMPLEMENTED ** Exit: - ** NOT IMPLEMENTED ** This call will copy the frame, converting as much as possible to the PC-ANSI character set. ** NOT IMPLEMENTED ** TTXHelper_ExtractLine &57184 Entry: R0 = Pointer to frame data. R1 = Which line to extract. Exit: R1 = Next line number, or -1 if finished. R2 = Extracted line. Side effects: This call will convert lines 1 to 26 of a standard 1040 byte block as is expected by the "Teletext" and "Teletext+" modules. The side effect is that, currently, the TTXHelper module will convert and out-of-range line number to a valid line number. For example: FOR loop% = 256 TO 512 : SYS "TTXHelper_ExtractLine", f, loop% : NEXT will provide you with 256 copies of line 26! A later version of TTXHelper will most likely return error &57184 in this case. This call, when given data and a line number (1-26), will return with the line data as a string. All trailing spaces will have been removed. This is for "save" routines, to do a text save, you would: REM open file here SYS "TTXHelper_ConvertToISO", fr%, wrkspc%, framelang% FOR line% = 1 TO 26 SYS "TTXHelper_ExtractLine", wrkspc%, line% TO ,, outline$ REM do whatever to save the line(s) here NEXT REM close file here You MUST convert the entire frame to ISO (or ANSI) and then call this function on the CONVERTED frame. Important: The lines are terminated with an &0D byte followed by an &00 byte. This allows them to work directly with BASIC software; while at the same time making it easy in C. In C, after extracting the line, we would do something like: linedata[ ( strlen(linedata) - 1 ) ] = '\0'; Generally, in a high level language, you would use a FOR...NEXT kind of loop. In order to maybe make things a little more efficient if you are writing in assembler, R1 is returned with the value of the NEXT line to be read, or -1 if completed. TTXHelper_UseInterface &57189 Entry: R0 = 0 to use system IIC bus 1 to use PtrIIC connection 2 to use RiscTV method Other values reserved. Exit: R0 = 0 if okay, else pointer to error block Possible errors: &81B511 "Invalid device ID passed to TTXHelper_UseInterface" You specified something other than 0, 1, or 2 in R0. &81B512 "No hardware/software support for device ID passed to TTXHelper_UseInterface" Before using the device that you have specified, TTXHelper ensures that a driver is loaded. If one is not loaded, this error will be returned. This call allows you to set up the interface method for the hardware access functions (below). It is recommended that you call this before calling any of hardware access functions. Please note that when you choose a device, TTXHelper will validate that the hardware/software support exists. IMPORTANT: Currently, if you do NOT explicitly call this SWI, TTXHelper will assume that you wish to use the system IIC bus. A later version of this module is likely to prevent any low-level hardware access until you have defined what interface to use (...by calling this SWI). TTXHelper_ReadBytes &5718A Entry: R0 = Row position (1 to 24) R1 = Column position (1 to 40) R2 = Pointer to data buffer R3 = Number of bytes to read (1 to 1024) Exit: R0 = 0, or pointer to error block. Data block updated. Possible errors: &81B513 "Invalid number of bytes to transfer (should be 1 - 1024)" &81B514 "Invalid row number (should be 1 - 24)" &81B515 "Invalid column number (should be 1 - 40)" &xxxxx [error returned during call to teletext hardware] Reads one or more bytes from the specified location in the receiver's on-board memory. Please note that the values count from *ONE*, not zero. The top left of the 'screen' is 1,1. TTXHelper_WriteBytes &5718B Entry: R0 = Row position (1 to 24) R1 = Column position (1 to 40) R2 = Pointer to data R3 = Number of bytes to write (1 to 1024) Exit: R0 = 0, or pointer to error block. Possible errors: &81B513 "Invalid number of bytes to transfer (should be 1 - 1024)" &81B514 "Invalid row number (should be 1 - 24)" &81B515 "Invalid column number (should be 1 - 40)" &xxxxx (error returned during call to teletext hardware) Writes one or more bytes to the specified location in the receiver's on-board memory. TTXHelper_ReadRegister &5718C Entry: R0 = Register R1 = Pointer to data buffer R2 = Number of bytes to read Exit: R0 = Null, or pointer to error block. Possible errors: &81B516 "Error while reading/writing register" &xxxxx (error returned during call to teletext hardware) Reads one or more specified SAA524x registers. Please refer to a datasheet for the teletext decoder IC for further details. TTXHelper_WriteRegister &5718D Entry: R0 = Register R1 = Pointer to data R2 = Number of bytes to write Exit: R0 = 0, or pointer to error block. Possible errors: &81B516 "Error while reading/writing register" &xxxxx (rror returned during call to teletext hardware) Writes one or more specified SAA524x registers. Please refer to a datasheet for the teletext decoder IC for further details. TTXHelper_ReadChapter &5718E Entry: R0 = Chapter to read, 0 or 4 R1 = Pointer to data buffer Exit: R0 = 0, or pointer to error block. Possible errors: &81B517 "Invalid chapter (should be 0 or 4)" &xxxxx (error returned during call to teletext hardware) This reads a chapter (1024 bytes) directly from the teletext receiver. Basically, standard page data appears on page zero while extension packets ("ghost rows") appear in chapter four. If you wonder why it is 0 and 4 (not 0,1 or 1,2 etc) then refer to the datasheet for the SAA524x teletext receiver IC(s). TTXHelper_ClearTSDP &5718F Entry: - Exit: R0 = 0, or pointer to error block. Possible errors: &xxxxx (error returned during call to teletext hardware) This clears the bytes of extension memory used for the TSDP. This may be required as the TSDP updates upon receipt of a new TSDP packet. When hopping through channels that do not support the TSDP, the old (last updated) TSDP would be returned. This call will blank it out so you know if no new TSDP arrives within ~1 second (best to wait about 140cs) then you may be assured that the current service doesn't offer a TSDP. TTXHelper_?????? &5718x Entry: - Exit: - Two further SWIs are available, but not by name. These are reserved for internal test functions and, as such, are not documented. For all other SWIs, you will receive the error: &81B518 "This TTXHelper SWI (&5718x) is not currently implemented." In order to make things a little bit easier in debugging, the error message reflects the SWI actually called [though note that the OS handles 'X' form SWIs, so if you call &77185 then TTXHelper would see &57185]. *Commands --------- These commands have not been officially registered. Given that they are all prefixed with "TTXHelper_", I do not anticipate any clashes to occur in a hurry... (unless somebody tries) *TTXHelper_Licence This command prints out some basic 'licence' text; either as a *Help message, or as a command in its own right (both do the same thing). Example output: This module is Copyright © 2004 Rick Murray. It may be used and redistributed according to the licence which should have been supplied alongside this module. You can obtain the latest version of this module, plus my other Teletext-related software, at: http://www.heyrick.co.uk/software/ttx/ Notes: If somebody has applied for a special version of this module, or for it to be used in a different way than described in the standard licence, then it will say so here. Possible errors: None. *TTXHelper_Probe This command tries to auto-detect your teletext receiver. It will then print a report of what it finds. This may be useful for testing teletext hardware without delving into the SWI calls. Example output (if device found): Found teletext receiver... Apparently compatible with the Ground Control/Octopus UTA-3. Connected via PtrIIC (parallel). Receiver internal memory is 2048 bytes. Example output (if device not found): Unable to detect any teletext receiving hardware. Notes: This command scans for devices on the internal IIC bus (if present), then PtrIIC (if present), and finally RiscTV's IIC bus (if present). It will report the FIRST device found. If you produce different IIC bus hardware for RISC OS machines, and you are willing to loan me the hardware, please contact me if you wish for your hardware to be supported within TTXHelper. Other support (such as SWI state mapping) can be provided. Possible errors: You should not receive any errors, simply a report of whether or not any hardware was found. *TTXHelper_View <filename> This command allows you to view teletext frames in a MODE 7 display. Notes: This only works within the single-tasking command line. If you try to do this in a taskwindow, you'll get an error message returned. TTXHelper_View isn't too fussy about its input. It will attempt to render pretty much anything as a teletext frame; including JPEGs of Alyson Hannigan, executables, letters to your friends... so long as it can read 1000 bytes, it'll display them to you - as teletext! :-) Possible errors: &81B519 "Sorry, you cannot view teletext frames in the desktop environment. Please go into the single-tasking command line [F12] and try again." Contact ------- If you have any questions or queries regarding this module, please contact me by email: rickttx @ bushinternet.com Please do not post this address anywhere 'public'. You can always find out about this module, and my other teletext software, by visiting: http://www.heyrick.co.uk/software/ttx/ [end of document]
This licence concerns the following data: In the base directory: "TTXHelper", RISC OS relocatable 'module' Within the "TTXH_Docs" subdirectory: "TTXHelpDoc", documentation for the above module "Licence", this document "Versions", change log for the above module Within the "Test" subdirectory: "_testmod", test software for the above module "!ReadMe", explanation of the testing procedure "_testfrmcv", Teletext frame for the above test software "_testfrmfl", Teletext frame for the above test software When this licence refers to the grouping of the software and its support documentation/software, it is referring to ALL of the above files. Typically the latter three 'test' files are in a subdirectory "test", while the documentation is in a subdirectory "TTXH_Docs". You may relocate any of the files, within reason, to suit your own application structure (this includes putting the test software directory within the documents directory, but please keep the test software in a SEPARATE subdirectory as it generates a number of output files that would clutter the documents directory). You may also relocate the module itself, i.e. "<YourApp$Dir>.Modules.TTXHelper" if this is how you arrange things. ALL of the files MUST be supplied within your own product unless you have my prior permission to do otherwise. The licence below states the terms within which you may use and/or (re)distribute this software. Please be aware that your use of this software in ANY form (including passing it to any third party and not 'using' it yourself, per-se) implies that you have read the following licence and you agree to be bound by all if its terms. Licence ------- You do not *have* to abide with this licence because you have not signed it. However, if you wish to use my software - the "TTXHelper" module, and its documentation and resources - then you will need to abide with this licence as it is the entity that grants you with my permission to use my software. No other entity, unless written by me, grants you permission to use my software. Either take it (all) or leave it (all). Please read this carefully, and remember that the use of the software will implicitly mean that you agree to be bound by the totally of this licence. All of the conditions in this licence apply to YOU. The section headings are only used to break the licence into useful sections. FOR EVERYBODY 1. This software "TTXHelper" and its documentation and test files are: Copyright © 2004 Rick Murray This software package is entirely my own work. 2. This software is supplied as-is. I, Rick Murray, accept no responsibility or liability for any loss or damage through the use (or misuse) of this software, without exception of any kind. Likewise, there is no warranty for this software, again without exception. 3. I do not imagine that the internal processes of this software will be a cause for a software patent; however in the eventuality that it is, it is hereby requested that any software patents applied to any part or process within this software is patent licenced for the free use of everybody, or not licenced at all. 4. You may NOT link this module into any form of 'hard' memory (ROM, FlashROM, EPROM, etc). This is because it writes to its own data areas, it is *not* ROMable. Contact me if you require a ROMable version to be produced for inclusion in your firmware. 5. For the purposes of legal dispute: a. This module, its documentation and resources are to be covered by the jurisdiction of the European Court. This, incidently, allows you more freedoms than you may have in other places, for example the freedom to examine the executable for "educational purposes". b. Any dispute regarding this module has NOTHING to do with the application using it, and vice versa, UNLESS the application is calling 'undocumented' features or otherwise using the module incorrectly. c. As I am not legally trained, I request that any judgement made regarding this licence is based upon the SPIRIT of the licence, and not upon the actual words that I have chosen and their order within the grammatical structure of our sometimes-ambiguous language. d. If you are using the software to which this licence applies, it will be taken as implied evidence that you agree to the full terms of this licence, without qualification; and they you fully understand all of the terms of this licence. e. If this licence, or any part of it, is not valid in your country or territory; or if any part of it is found to be invalid, then the ENTIRE licence will be revoked and you must cease using the software. f. Under international copyright laws, you do not have any "right" to use my software unless I specifically say that you may. This licence is my permission to you to use, copy, and distribute my software. This permission is granted as long as: i. This licence is legally valid and: ii. You abide by its terms Failure of you to abide, or failure of the licence, revokes the permission that I have granted to you, this meaning that your (continued) use of the software is therefore an illegal act. g. If you have any doubts, please contact me at the email address given previously in this document. I do not have any agents, nor have I appointed anybody to speak on my behalf, nor are lawyers in a position to instruct anybody as to what they think I might mean... if you have ANY doubts or questions, your sole remedy is to contact me. Do not "assume" things when you can ask... 6. I reserve the right to modify the terms of this licence at any time, however those modifications will NOT be retrospective; you will not be expected to comply with the newer licence if you are still using the older software. However upgrading to the newer software will require you to accept the newer licence. You cannot apply a newer licence to any version of the software that was originally supplied with an older version of the licence. If a newer version of the software comes with a version of the licence that you do not agree to, you may continue using the older software with the licence that you do agree to. Do not use the newer version. Please contact me to discuss what you don't agree to. 7. In the (undesired!) event of my death, "all bets are off" and, quite frankly, I'll be dead so what the hell would I care what happened with my software then? Upon my legally verified death, this licence will be revoked and you will be granted a (posthumous) permission to do whatever you like with this software... FOR SOFTWARE DEVELOPERS AND DISTRIBUTORS 8. You may distribute the TTXHelper software within your own application provided that: a. It actually USES my software! b. You distribute the module UNMODIFIED. This includes, but is not limited to: i. Binary-level modifications ii. Disassembly, patching, and reassembly iii. Renaming the module to anything other than "TTXHelper" It is permissable for an automatic agent to modify this software provided that: i. It is completely automated and 'background' (i.e. AppPatcher) ii. It is for the process of compatibility with an emulated RISC OS based system (i.e. Aemulor) iii. The patches can apply to any 'compatible' module generally, and not to "TTXHelper" specifically iv. Or, any patches necessary in anti-viral protection systems, such as automatically-embedded CRC numbers appended to the end of the file. c. You must also distribute the accompanying documentation and test software along with the module, in every instance. d. A notice, visible on-screen, saying that you are using my module would be appreciated, but it is not mandatory e. The following depends upon whether your software is free or not. i. If your software is "free" (completely gratis, i.e. I can go to your website and download a completely functional unrestricted and 'full' version of the software...), then all I would like in return is a quick email stating what you are using my software for - and feel free to let me know if you have any ideas for future improvements! I will download your software at my discretion (which, since I'm a download junkie, will likely be moments after reading your message!). ii. If your software is not "free" (shareware, charityware, commercial, etc; anything for which money or other remuneration is required of the end-user *even* if the money does not go to you (such as "please pay X to charity Y") then I would like to receive, in trade, a gratis and fully working copy of your application (with all required resources for its correct functioning). Contact me if you have any queries. f. This module is covered by this licence. Your own licence cannot override this, specifically: i. Your end-users may take a copy of this module for their own use (including within their own software) provided that they agree to be bound by this licence. ii. This module and its resources are NOT released under the GPL scheme known as the "GNU General Public License". There seems to be some form of confusion regarding the omnipotence of the 'famous' GNU developers, in that their GPL is apparently believed to 'infect' certain software when used in certain ways, and that the GNU head-honcho can settle any dispute with a nod. Maybe in the land of the idyllic, this can occur. Here in The Real World, where this licence prohibits any form of merge with GNU's GPL, it is up to you to make certain that this is not a possibility if your software is not GPL. If it should transpire that this software has been used in such a way that it brings it under the GPL, then this use is to be considered invalid; and NOT the other way around (so please don't even bother trying 'hey, your module is now GPL, give us all your source code!' ruse - I'm not falling for it. iii. All of this applies, all the way down the line, for all use of this software. iv. Obviously, this licence does not affect your own application or the restrictions that you place upon it. 9. You may NOT link this module into any form of 'hard' memory (ROM, FlashROM, EPROM, etc). This is because it writes to its own data areas, it is *not* ROMable. Contact me if you require a ROMable version to be produced for inclusion in your hardware/firmware. 10. This software may NOT be supplied on its own (i.e. not as part of a software package), except as specified in the non-exhaustive list below: a. If an important update to this software appears and you USE this software within your application, you may offer the update to your users via your usual upgrade systems provided that you do not ask an unreasonable fee for doing so. b. This software may be supplied on a bulletin board service (BBS), website, or ftp archive provided that any casual visitor (such as myself) can download the file without paying any kind of "registration fee" or subscription, etc. i. I would appreciate any website carrying this software to provide a link to its homepage, so your visitors may be assured that they will be able to find the most up-to-date copy. This, however, is not mandatory. Just good manners. :-) c. Any form of hard media copy (floppy disc, CD-R, etc) is allowed provided that the entire package costs no more than 5 euros (this is roughly 3.50 pounds sterling or 6.25 US dollars). By "entire package", this would prohibit (non-exhaustively): i. Magazine cover-mount discs (the disc and the magazine are an entire 'package', the two don't count separately). ii. "Free" software bundled with a commercial application (this does not apply if your application actually makes use of my software, and you have complied with ALL of part 8). iii. "ShareWare" collection CD-ROMs, "compendium" CD-ROMs, etc. If you fall into case 'i' or 'iii', please email me. I will, usually, let you distribute a copy of the software in return for a free version of whatever it is you are making. It is also good manners, before releasing something like that, to ensure you have the most up-to-date version. If you fall into any of these cases, you are forbidden from distributing this software unless you have specifically obtained my permission beforehand... It is NOT valid to claim that you "made 'reasonable attempts' to contact me, and then went and put this software on some form of media in the event of my not replying to your communications". I have been in that game before - my software displayed a clear and valid email address (that was working at the time) in both the program information window and it's documentation, and this email address was actually stated as my contact email in a CD-ROM index file, but somehow they never thought to actually contact me! It's a shame, as not only was it annoying, but they managed to burn a 'broken' (development) version of the software onto their CD; we all make silly mistakes like that from time to time, I actually noticed and re-uploaded two days later. However, the bad version was committed to CD (didn't they bother to test it!?!?), and it makes me look like an idiot (well, more so than I usually look). If you reject this licence, it is illegal to use or copy this software. If you use or copy this software, it'll be taken that you are happy with all of the terms of this licence and agree to be bound by them. If you have ANY questions or queries, contact me at the email address that is stated in the module help file.
Return to Teletext software index