home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / t / texturegnd / Docs / Extensions < prev    next >
Text File  |  1996-11-30  |  26KB  |  676 lines
  1.  
  2.                         Language Extensions
  3.                         ===================
  4.  
  5. 1.0 Introduction
  6. 2.0 The RMStore directory
  7. 3.0 Structure
  8. 4.0 Resources
  9. 5.0 Coding
  10. 6.0 Calling internal commands
  11.  
  12. 1.0 Introduction
  13. ~~~~~~~~~~~~~~~~
  14. This document describes how to write language-extensions to the texture
  15. generation language used in the Texture Garden program, reasons why you might
  16. be interested in doing this and information about installing other people's
  17. extension modules.
  18.  
  19. Commands may be included, but functions (refer to the "Language" file for the
  20. differences between these) may not currently be implemented by third parties.
  21.  
  22. Example source code using the BASIC assembler is available. It is no longer
  23. commonly distributed with the main TG archive (for reasons of space), and
  24. the entire source code for Texture Garden's Kernel is also available.
  25. Although this code is distributed as freeware (i.e. copyright is retained)
  26. the author expresses every intention of approving use of my code where it is
  27. incorporated into modules intended for my program, so please do not hesitate
  28. to steal and butcher it; if this was objected to no source code would have
  29. been distributed.
  30.  
  31. 2.0 The RMStore directory
  32. ~~~~~~~~~~~~~~~~~~~~~~~~~
  33. This is a directory immediately inside the "!TexturGdn" directory.  The
  34. location is usually "<TextureGdn$Dir>.RMStore".  The precise location is held
  35. in the system variable <TextureGdnRMStore$Dir> which is usually set up in the
  36. !Run file.
  37.  
  38. This directory should always contain a text file called "Index".  This file
  39. has a simple format:
  40.  
  41. Any line starting with a "|" is considered to be a comment. The end of the
  42. file is marked by the "End" token. Any other lines are considered as paths
  43. from <TextureGdnRMStore$Dir> to files containing language extensions.
  44.  
  45. The file "Kernel" should always be present in the directory.  It contains all
  46. the commands implemented as the core of the language.  There may also be
  47. other files.
  48.  
  49. The files may be of any type.  Conventionally, they are "Modules"
  50. (Type &FFA).  Though they are not loaded as such by the program this enables
  51. them to conveniently contain a version number and help text.
  52.  
  53. When adding extension modules to the program the relevant file should be
  54. added to the "RMStore" directory and the twig of its path inserted into the
  55. "Index" file.
  56.  
  57. 3.0 Structure
  58. ~~~~~~~~~~~~~
  59. Language extensions should all conform to the following structure:
  60.  
  61. Bytes:        Description...
  62. &0000-&002B   Header (Undefined bytes)
  63. &002C-&XXXX   Command Table index
  64. &XXXX-&YYYY   Command Table
  65. &YYYY-&ZZZZ   Command code
  66.  
  67. The Command Table index has the following format:
  68.  
  69. Offset bytes: Description...
  70. &0000           Command index entry 0
  71. &000C          Command index entry 1
  72. &0018          Command index entry 2
  73. -             -
  74. n x &C        Command index entry n
  75. -             -
  76. &UUUU         End of table marker.
  77.  
  78. The End of table marker is represented by the three consecutive words 
  79. -1,-1 and -1.
  80.  
  81. Command index entry n consists of three words
  82.  
  83. Word 0: Offset from start of file to the text of command n.
  84. Word 1: Offset from start of file to the entry point of the code to perform
  85.         the command.
  86. Word 2: Various flags
  87.  
  88. The Various flags are considered as &ABCDEFGH where &A is the number of
  89. parameters the command accepts (0-15), &B is a code advising how the command
  90. should be treated by the mutator (the "Mutation Options"), and &CDEFGH
  91. contain other miscellaneous bit-flags to mark specific command types.
  92.  
  93. These bit-flags have the following meanings:
  94.  
  95. &000003 :                                           (Reserved)
  96. &00000C : See immediately below:
  97.      &4 : Command ends an indentation
  98.      &8 : Command starts an indentation
  99. &0000F0 :                                           (Reserved)
  100. &00FF00 : As follows:
  101.   &0C00 : Command is an "endif"                     (Reserved)
  102.   &0200 : Command starts mutation                   (Reserved)
  103.   &0300 : Command stops  mutation                   (Reserved)
  104.   &0400 : Command is a  "Define"                    (Reserved)
  105.   &0500 : Command is a  "Goto"                      (Reserved)
  106.   &0600 : Command is a  "Call"                      (Reserved)
  107.   &0700 : Command is a  "Return"                    (Reserved)
  108.   &0800 : Command is an "End"                         (Reserved)
  109.   &0900 : Command is an "If"                         (Reserved)
  110.   &0A00 : Command is an "Then"                      (Reserved)
  111.   &0B00 : Command is an "Else"                      (Reserved)
  112.   &0100 : Command is a  "comment" ("|")             (Reserved)
  113.   &0D00 : Command ends the colour definition        (Reserved)
  114.   &0E00 : Command starts the colour definition      (Reserved)
  115.   &0F00 : Command is a  "CreateOneDiensionalFilter" (Reserved)
  116.   &1000 : Command is a  "CreateTwoDiensionalFilter" (Reserved)
  117.   &1100 : Command is an "Until"                     (Reserved)
  118.   &1200 : Command is a  "Resize"                    (Reserved)
  119.   &1300 : Command is a  "ResizeSprite"              (Reserved)
  120.   &1400 : Command is a  "MakeSprite"                (Reserved)
  121.   &1500 : Command is an "AddToSprite"               (Reserved)
  122.   &1600 : Command is a  "MakeVirtualSprite"         (Reserved)
  123.   &1700 - &FF00 For expansion                       (Reserved)
  124. &FF0000 : Bits all for expansion and must be zero   (Reserved)
  125.  
  126. "Reserved" means that most users should not need to mess with it.
  127.  
  128. The "Command Table" contains the entries pointed to by word 0 of the Command
  129. index entry.  These are mixed case strings terminated by a single ASCII 13
  130. character.  They need not be word aligned.
  131.  
  132. The "Command code" contains the code pointed to by word 1 of the Command
  133. index entry.  These are ARM code subroutines called at the appropriate moment
  134. in the generation of the textures.  Any workspace may also be stored here,
  135. rather than claimed from the system, if it is small enough.  The location of
  136. the "Command code" relative to the "Command table" is arbitrary.
  137.  
  138. Mutation Options
  139. ~~~~~~~~~~~~~~~~
  140. This specifies how any following parameters are treated by the mutator.
  141. 0 - Completely ignore.
  142. 1 - Treat as unsigned 16-bit logarithmic number (reserved for functions)
  143. 2 - Very occasionally add or subtract one (used for "Shear")
  144. 3 - Occasionally completely randomize (used for "Seed")
  145. 4 - Treat as unsigned 16-bit logarithmic number
  146. 5 - Treat as a SetColour command...
  147. 6 - Treat as a DefineLightSource command.
  148. 7 - Reserved...
  149.  
  150. 4.0 Resources
  151. ~~~~~~~~~~~~~
  152. When a code fragment is called in the generation of a texture it may interact
  153. with the main program and share its data in a number of ways.
  154.  
  155. On entry to the routine the following register conventions are used:
  156.  
  157. R14 - return address
  158. R13 - system stack
  159. R12 - pointer to Texture Garden main data structure
  160. R11 - pointer to current point in texture program execution
  161.  
  162. On exit R0 - R10, R12 and R14 may be corrupted.  R11 should normally be
  163. incremented to the start of the next expected command.  R13 should normally
  164. be preserved in the normal manner.
  165.  
  166. R11 contains a pointer to the next item in the texture program's execution.
  167. This will always be the next item after the code representing the currently
  168. called command.  Note that the program is not held internally as a textfile,
  169. but in an internal format.
  170.  
  171. Each command, parameter or function is coded for by one word.  Parameters are
  172. coded for by their values.  Commands and functions are coded bu an internal
  173. number, the complete details of which are not specified, but which always has
  174. bit 31 set.  The end of the file is coded as -1.  This need not normally be
  175. checked for.
  176.  
  177. R12 contains a pointer to a data structure which has the following structure:
  178.  
  179. Brief list:
  180.  
  181. Routines
  182. ~~~~~~~~
  183. &0000 : TG_getrnd - routine returning 32bit random number in R3
  184. &0004 : TG_getrnd2 - routine returning 32bit random number in R3
  185. &0008 : TG_getparameter - routine returning the value of the next parameter
  186. &000C : TG_cstable - location of sin and cosine table.
  187. &0010 : TG_astable - location of arcsin table.
  188. &0014 : TG_forstac - location of stack of for addresses
  189. &0018 : TG_forcoun - location of stack of for addresses
  190. &001C : TG_itisthecodebank - location of 16 words of ARM code for "Combine"
  191. &0020 : TG_onedimensionalfixsta - routine to start