home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / dde / datatoaof / Guide next >
Encoding:
Text File  |  1993-03-11  |  8.8 KB  |  308 lines
  1.                                     !DataToAOF
  2.  
  3.                                   By Paul Fidler
  4.  
  5.                              version 1.00 (11th Feb 1993)
  6.  
  7.  
  8. About The Program
  9. ~~~~~~~~~~~~~~~~~
  10.  
  11. This program is designed primarily for C or ARM code programmers, who wish
  12. to store data of some sort or other within their programs. I wrote it so
  13. that I could store sprites files within !Runimage files, to stop people
  14. editing them.  
  15.  
  16. The program allows you to encapsulate any file within an AOF file that can
  17. then be linked into your program. This will allow you to include data,
  18. sprites, templates, drawfiles etc. inside the !RunImage file of your
  19. application, where they're safe from prying eyes.
  20.  
  21. I have written a replacement to the Risc_OSLib resspr functions to allow
  22. sprites files to be hidden. You will have to write functions to deal with
  23. any other sort of files yourself (although I hope to have replacement
  24. template functions ready soon).
  25.  
  26. Examples are provided to show you how to use text files and sprites files.
  27.  
  28.  
  29.  
  30. Installation:
  31. ~~~~~~~~~~~~~
  32.  
  33. Included with this file should be:
  34.  
  35. !DataToAOF Frontend application
  36. Library    Directory containing the command-line application
  37. Examples   Directory containing two example programs
  38. HiddenLib  Directory containing replacement resspr functions
  39. tool       Six line textfile to update !Make
  40. Guide      This file
  41.  
  42. 1) The '!DataToAOF' application should be placed in DDE$Path
  43.  
  44. 2) The 'Library.datatoaof' file should be placed in your library.
  45.  
  46. 3) The 'tool' textfile should be appended to the end of !Make.choices.tools
  47.    Note that there are exactly six lines per tool with no blank lines in 
  48.    between tools (although some of the six lines may be blank).
  49.  
  50.  
  51. !DataToAOF Application
  52. ~~~~~~~~~~~~~~~~~~~~~~
  53.  
  54. This is a Frontend application. You need to Frontend Module (supplied with
  55. the Desktop Development Environment) to run it. When run, the program
  56. installs itself on the icon bar. Clicking on the bar icon opens the main
  57. window. This contains the following icons.
  58.  
  59.       Icon               Action/Meaning                               Default
  60.       ----               --------------                               -------
  61.       File               Name of file to be stored                      nil
  62.                          (typed or dragged)
  63.  
  64.       Read Only          This sets the READONLY bit of the area         off
  65.                          attributes. You should set this if your
  66.                          data will not be written to by your
  67.                          program. At present, it makes little
  68.                          difference, whether or not it is set
  69.                          correctly, but future operating systems
  70.                          may insist on it.
  71.                            
  72.       Store length       This stores the length of the data file        on
  73.                          in the AOF file. Note that it is not
  74.                          sufficient to type something into the
  75.                          'Length's symbol' field (see below).
  76.                          If your program needs to know how long
  77.                          your original data file was, then you
  78.                          must set this icon.
  79.  
  80.       Store Data as      This makes the data's symbol a pointer.        on
  81.          pointer         Set it if you wish to use the data as a
  82.                          C array. If the data is to be accessed
  83.                          from Assembler, it is probably better not
  84.                          to use this option. See the Technical
  85.                          Details section for more information.    
  86.  
  87.       Data's symbol      This sets part of the name by which your       ""
  88.                          data is referenced from within your program
  89.                          It may be prefixed or appended by the 
  90.                          leafname of your data file if you desire
  91.                          (see below).
  92.  
  93.       Length's symbol    This sets part of the name of the variable   "_length"
  94.                          used to store the length of the data file
  95.                          in your program. It may be prefixed or
  96.                          appended by the leafname of your data file
  97.                          if you desire (see below).
  98.  
  99.       Prefix leafname    This prefixes the leafname of the data file    on
  100.                          to both 'Data's symbol' and 'Length's symbol'
  101.                          This is the default option if you use !Make.
  102.  
  103.       Append leafname    This is as for 'Prefix leafname' except that   off
  104.                          the leafname is appended.
  105.  
  106.       Omit leafname      This ensures that neither symbol is altered    off
  107.                          by the leafname.
  108.  
  109.  
  110.       N.B. If neither 'Prefix leafname', 'Append Leafname' nor 'Omit leafname'
  111.            are set, then 'Prefix leafname' is assumed by default.
  112.  
  113.  
  114.  
  115.  
  116. The datatoaof Command Line Tool
  117. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  118.  
  119. If you are writing your own MakeFiles, or if you prefer to enter commands from the command line, then you will need the information below:
  120.  
  121.  
  122. Command format: datatoaof -f <source_file> -o <output_file> [options]
  123.  
  124. Command options:
  125.  
  126. -D  <symbol>    Data's Symbol
  127. -L  <symbol>    Length's Symbol
  128. -DP             Makes Data's symbol a pointer. ie. (void *)
  129.  
  130. -R              Puts the data and symbol(s) in a Read only area.
  131. -S              Stores Length information.
  132.  
  133. -P              Prefixes the symbol(s) with the source's leafname.
  134. -A              Appends the symbol(s) with the sources leafname.
  135. -N              Omit's the the leafname.
  136.  
  137. The above is identical to the output of 'datatoaof -help'
  138.  
  139. In addition, if you do write your own MakeFiles, you should also include:
  140.  
  141. -depend !Depend
  142.  
  143. to the list, and this will sort out the dynamic dependencies section of your
  144. makefile automatically
  145.  
  146.  
  147.  
  148. HiddenLib
  149. ~~~~~~~~~
  150.  
  151. This section will only be of interest to C programmers. HiddenLib replaces
  152. the Risc_OSLib resspr_* functions. I hope it will eventually replace
  153. template_* as well.
  154.  
  155. To use the new version of resspr_* you must 'compile' your Sprites file with
  156. the 'Store length' option and without the 'Read Only' option.
  157.  
  158. A typical program would look like this:
  159.  
  160.  
  161.  
  162. /* Example /*
  163.  
  164. #include "resspr+.h"
  165. #include "baricon.h"
  166.  
  167. /* and so on */ 
  168.  
  169. /* declare the external references */
  170. extern int        sprites_length;
  171. extern spritearea *sprites;
  172.  
  173.  
  174. /* Put your program here */
  175.  
  176. void init_proc(void)
  177. {
  178.     
  179.     /* Do all your initialising */
  180.  
  181.     resspr_init(sprites, sprites_length);
  182.  
  183.     /* Do some more initialising */
  184. }
  185.                                    
  186.  
  187.  
  188. Look at Examples.Example2.!HideTest.c.HideTest for a complete example.
  189.  
  190.  
  191.  
  192. Technical Details
  193. ~~~~~~~~~~~~~~~~~
  194.  
  195. This section will mainly interest ARM code programmers.
  196.  
  197. The AOF files that datatoaof produces come in one of four varieties,
  198. depending upon whether the length is stored or not, and whether the data is
  199. stored as a pointer or not.
  200.  
  201.  
  202. The code fragments below show what is actually compiled.
  203.  
  204.  
  205.  
  206. 1) Length stored, Data is pointer
  207.  
  208.         EXPORT  |data_length|
  209.         EXPORT  |data_pointer|
  210.  
  211.         AREA |DataToAOF$$Data|, DATA    ; Possibly with ,READONLY as well
  212.  
  213. |data_length|
  214.         DCD     12345678        ; The length of your file.
  215. |data_pointer|
  216.         DCD     startofdata     ; The data pointer
  217.         DCD     00000000        ; Blank word
  218.  
  219. startofdata
  220.         DCB     "The file goes here"
  221.                                 ; The file data
  222.         ALIGN
  223.         END
  224.  
  225.  
  226.  
  227. 2) Length Ommited, Data is pointer
  228.  
  229.         EXPORT  |data_pointer|
  230.  
  231.         AREA |DataToAOF$$Data|, DATA    ; Possibly with ,READONLY as well
  232.  
  233. |data_pointer|
  234.         DCD     startofdata     ; The data pointer
  235.         DCD     00000000        ; Blank word
  236.  
  237. startofdata
  238.         DCB     "The file goes here"
  239.                                 ; The file data
  240.         ALIGN
  241.         END
  242.  
  243.  
  244.  
  245.  
  246. 3) Length stored, Data is first item
  247.  
  248.         EXPORT  |data_length|
  249.         EXPORT  |data|
  250.  
  251.         AREA |DataToAOF$$Data|, DATA    ; Possibly with ,READONLY as well
  252.  
  253. |data_length|
  254.         DCD     12345678        ; The length of your file.
  255.         DCD     00000000        ; Blank word
  256.  
  257. |data|
  258.         DCB     "The file goes here"
  259.                                 ; The file data
  260.         ALIGN
  261.         END
  262.  
  263.  
  264.  
  265. 4) Length ommited, Data is first item
  266.  
  267.         EXPORT  |data|
  268.  
  269.         AREA |DataToAOF$$Data|, DATA    ; Possibly with ,READONLY as well
  270.  
  271.  
  272.         DCD     00000000        ; Blank word
  273. |data|
  274.         DCB     "The file goes here"
  275.                                 ; The file data
  276.         ALIGN
  277.         END
  278.  
  279.  
  280.  
  281. You can use DecAOF to see exactly what is produced.
  282.  
  283.  
  284.  
  285. Bug Reports / Comments
  286. ~~~~~~~~~~~~~~~~~~~~~~
  287.  
  288. I would welcome any bug reports. I will do my best to fix them and release a
  289. new version as soon as possible.
  290.  
  291.  
  292. I can be contacted at:
  293.  
  294. email: praf1@uk.ac.cam.phx
  295.  
  296. term-time: Paul Fidler
  297.            Churchill College
  298.            Cambridge
  299.            CB3 0DS
  300.  
  301. vacations: Paul Fidler
  302.            17 Kenerne Drive
  303.            Barnet
  304.            Herts
  305.            EN5 2NW
  306.  
  307.  
  308.