                              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]
