home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilst / texturgdn / !TexturGdn / Docs / Language < prev    next >
Text File  |  1996-09-29  |  55KB  |  1,575 lines
  1.  
  2.          Texture Garden texture generation language specification
  3.          ========================================================
  4.            
  5.     This file documents version 0.44 of the texture generation language
  6.           This is distributed with Texture Garden version 0.44.
  7.  
  8. 1.00 Introduction
  9. 1.10 The format of this file
  10. 2.00 Writing textures
  11. 2.10 Syntactic considerations
  12. 3.00 Command summary (commands grouped by class)
  13. 4.00 Command details (commands grouped by class)
  14.  
  15. 1.00 Introduction
  16. ~~~~~~~~~~~~~~~~~
  17. The Language:
  18.  
  19. When editing texture generation programs, some syntactical rules need to be
  20. beone in mind.  The language is a compromise between three design criteria:
  21.  
  22. 1: That it should be readable by a human
  23. 2: That it should be editable by the computer.
  24. 3: That it should go like the clappers.
  25.  
  26. Compactness was not considered to be particularly important. 
  27. Characteristically commands are verbose.  It is recommended that typing in
  28. commands using longhand is to be avoided and that cut and paste facilities
  29. are employed wherever possible.
  30.  
  31. When loaded, commands are translated into an internal format and the original
  32. textfile is discarded.  Loaded files may contain command names in any case,
  33. truncated names, commands optionally abbreviated with the "." character,
  34. confused and confusing punctuation and mismatched brackets.  When the file is
  35. saved, it is cleaned up, reformatted and expanded into a standard format. 
  36. Unless you know what you are doing, keeping copies of the original files is
  37. recommended, as What The Computer Thinks You Are Talking About may initially
  38. differ from What You Are Trying To Say.
  39.  
  40. Error checking is currently implemented mainly at the parsing stage.  If the
  41. program you feed the computer contains errors, the message will tell you
  42. which line they are found on.  These messages should be helpful in the
  43. process of tracking down mistakes.  Runtime error messages are supported, but
  44. should occur very rarely in practise.
  45.  
  46. If your version of this program is unregistered, then you will probably
  47. experience difficulties in changing existing textures or getting your own
  48. textures to be displayed.  Please refer to the "Register" document for
  49. details of why this occurs.
  50.  
  51. Resources:
  52.  
  53. There are currently several main resources available for use in generating
  54. textures.  The texture generation program "sees" a virtual machine with a
  55. variety of storage media and one primary output channel.
  56.  
  57. There are three one dimensional buffers of &400 16-bit values which may be
  58. manipulated.   One two dimensional buffer is provided, with dimensions
  59. controlled by the size of the sprite to be generated.  A buffer for storing
  60. colourmaps exists and there is space reserved for the manipulation of &400
  61. variables.  These contain unspecified values on entry to the routine.
  62.  
  63. Texture generation programs are entered when a texture is required.  Their
  64. execution begins at their first line.
  65.  
  66. 1.10 The format of this file
  67. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  68. In the command summary which follows, each command is named and then it is
  69. followed by a string in brackets indicating what kind of parameters it takes.
  70. If there are no brackets then the command takes no parameters.  In the second
  71. part of the document, descriptions of the operation of each of the commands
  72. are also given.
  73.  
  74. Comments are considered to be anything after a "|" character.  Comments in
  75. If...Then...Else lines are treated using the same conventions as in Obey
  76. files, i.e. "If 1 = 2 THEN |ECHO Equal! ELSE ECHO Not_Equal!" would print
  77. "Not_Equal!" in an Obey file, despite the earlier "|".
  78.  
  79. 2.00 Writing textures
  80. ~~~~~~~~~~~~~~~~~~~~~
  81. Conventions:
  82.  
  83. All textures should begin with a definition of their primary palette enclosed
  84. by the commands "StartColourDefinition" and "EndColourDefinition".
  85.  
  86. Textures terminate when they reach the "End" command.  It is conventional to
  87. place subroutine definitions after the "End" so they are seperate from the
  88. main program.  The mutator may rely on this in the future.
  89.  
  90. 2.00 Syntactic considerations
  91. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92. Essentially, the syntax of the language is simple.  
  93.  
  94. Everything falls into one of four categories.  
  95.  
  96. These four categories are: Comments, Commands, Functions and Parameters.
  97.  
  98. Comments are simple: they are considered to be anything after a "|"
  99. character.
  100.  
  101. Commands come in three types: Conditional, Ordinary and Branch commands.
  102.  
  103. Conditionals have the form: "If <Condition> Then <Command> Else <Command>". 
  104. The "Until <Condition>" command also comes into this category.
  105.  
  106. Ordinary commands normally appear at the start of each line.  They may have
  107. zero or more parameters.  If they have parameters then these are enclosed in
  108. brackets.
  109.  
  110. Branch related commands come in several types.  "Define <DefinitionMarker>"
  111. sets a named mark at a point in the file, "Call <DefinitionMarker>" calls the
  112. relevant "Define" and continues until a "Return" is encountered. 
  113. "Goto <DefinitionMarker>" simply continues execution from the relevant
  114. "Define".
  115.  
  116. Functions may be given instead of parameters.  They should never appear at
  117. the start of a line.  Functions are defined over the domain (&0000-&FFFF). 
  118. They generally range over (&0000-&FFFF).  That they have the same range as
  119. their domains means that it is convenient to feed the results of functions
  120. to other functions as parameters.
  121.  
  122. Parameters may cover the range from &0000 to &FFFF.  They may be given as
  123. signed or unsigned, decimal or hexadecimal (with a preceeding "&") integers. 
  124. Where a paramter is required, this may be given as a constant numerical value
  125. or as a function.  Variables may be used and are implemented as simple
  126. functions.
  127.  
  128. Textures are not especially sensitive to punctuation mistakes, spaces, or
  129. other idiosyncrasies.  If brackets are mismatched, the program guesses where
  130. they should be and inserts them.  This is useful when editing textures in a
  131. text editor.
  132.  
  133. 3.00 Command summary (commands grouped by class)
  134. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  135. 01 Functions
  136. ~~~~~~~~~~~~
  137. Combine(Type,A,B)
  138. ScaledSignedMultiply(A,B)
  139. SignedMultiply(A,B)
  140. PartlyScaledSignedMultiply(A,B)
  141. PartlyScaledMultiply(A,B)
  142. Divide(Numerator,Denominator)
  143. Eor(A,B)
  144. And(A,B)
  145. Or(A,B)
  146. Absolute(A)
  147. LogicalShiftLeft(A,Exponent)
  148. LogicalShiftRight(A,Exponent)
  149. ArithmeticShiftLeft(A,Exponent)
  150. ArithmeticShiftRight(A,Exponent)
  151. Variable(Variable_Number)
  152. Random(And_value,Eor_value)
  153.  
  154. 02 Types
  155. ~~~~~~~~
  156. SimpleAddition
  157. UnboundedAddition
  158. CeilingAddition
  159. HalvingAddition
  160. SimpleSubtraction
  161. UnboundedSubtraction
  162. FloorSubtraction
  163. HalvingSubtraction
  164. Maximise
  165. Minimise
  166. Overwrite
  167. PositiveOverwrite
  168. Preserve
  169. Multiplication
  170. ScaledMultiplication
  171. Zeroise
  172.  
  173. 03 Constants
  174. ~~~~~~~~~~~~
  175. True
  176. False
  177. Zero
  178. Ninety
  179. OneHundredAndEighty
  180. TwoHundredandSeventy
  181. FloydSteinberg
  182.  
  183. 04 Variables
  184. ~~~~~~~~~~~~
  185. X
  186. Y
  187. Z
  188. Size
  189. LogSize
  190. LogBitsPerPixel
  191. AnimationFrameNumber
  192. AnimationType(Frequency)
  193.  
  194. Sin(Theta)
  195. Cos(Theta)
  196. SignedSin(Theta)
  197. SignedCos(Theta)
  198. SquareRoot(Value)
  199.  
  200. 05 Section of Functions of X and Y
  201. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  202. Noise(Intensity,MaximumFrequency)
  203. PinkNoise(Intensity,MaximumFrequency)
  204. QuickNoise(Intensity,MaximumFrequency)
  205. BandpassNoise(Intensity,MinimumFrequency,MaximumFrequency)
  206. BandpassQuickNoise(Intensity,MinimumFrequency,MaximumFrequency)
  207. FractalNoise(MaximumIntensity,FractalDimension)
  208. ShiftedSymmetricNoise(Intensity,MaximumFrequency,X,Y)
  209. ShiftedSymmetricPinkNoise(Intensity,MaximumFrequency,X,Y)
  210. ShiftedNoise(Intensity,MaximumFrequency,X,Y)
  211. ShiftedPinkNoise(Intensity,MaximumFrequency,X,Y)
  212. ShiftedSymmetricQuickNoise(Intensity,MaximumFrequency,X,Y)
  213. ShiftedQuickNoise(Intensity,MaximumFrequency,X,Y)
  214. ShiftedSymmetricFractalNoise(MaximumIntensity,FractalDimension,X,Y)
  215. ShiftedFractalNoise(Intensity,MaximumFrequency,X,Y)
  216.  
  217. TwoDimensionalPoint(X,Y)
  218. OneDimensionalPoint(X)
  219. OneDimensionalPointOne(X)
  220. OneDimensionalPointTwo(X)
  221. QuickTwoDimensionalPoint(X,Y)
  222. QuickOneDimensionalPoint(X)
  223. QuickOneDimensionalPointOne(X)
  224. QuickOneDimensionalPointTwo(X)
  225.  
  226. 06 Miscellaneous
  227. ~~~~~~~~~~~~~~~~
  228. Beep
  229. Bell
  230. End
  231. Checksum(Value)
  232. UnknownCommand
  233.  
  234. 07 Conditional
  235. ~~~~~~~~~~~~~~
  236. If <Condition> Then <Command> Else <Command>...
  237.  
  238. IsLessThan(A,B)
  239. IsGreaterThan(A,B)
  240. IsLessThanOrEqualTo(A,B)
  241. IsGreaterThanOrEqualTo(A,B)
  242. SignedIsLessTha