home *** CD-ROM | disk | FTP | other *** search
/ The Devil's Doorknob BBS Capture (1996-2003) / devilsdoorknobbbscapture1996-2003.iso / Dloads / SYSOP / ADRAW120.ZIP / SAUCE.TXT < prev   
Text File  |  1995-05-28  |  22KB  |  491 lines
  1. ┌──────────────────────────╖
  2. │ What is SAUCE?           ║
  3. └══════════════════════════╝
  4.  
  5.    Recipe for SAUCE
  6.  
  7.    Chef cuisinier : Tasmaniac / ACiD
  8.    Maitre d'hôtel : Rad Man / ACiD
  9.  
  10.         ANSi's used to be just ANSi's,  pictures  were just pictures,
  11.    loaders were just loaders  and quite frankly,  every file was just
  12.    as plain tasting as every  other.  This  is  about to change, how-
  13.    ever,  because  ACiD  has decided to give  their  files  an  extra
  14.    "je-ne-sais-quoi."  In  reality,  we'll  be  adding SAUCE to every
  15.    file you can imagine.
  16.  
  17.         Now, before we thoroughly confuse you, let us explain what we
  18.    are doing  here.  SAUCE  stands  for  "Standard  Architecture  for
  19.    Universal  Comment  Extensions."  Although originally intended for
  20.    personal use in ANSi's and RIP screens,  early in the developement
  21.    of EFI (Extended File Information) it  was decided that EFI should
  22.    be extended  to  have  support  for  more  than  just ANSi and RIP
  23.    screens.  Our brainchild  was  born  and  the specs were designed.
  24.    The only aspect left  undecided was the name,  and after rejecting
  25.    some very funny candidates,  SAUCE  was  unanimously chosen.  This
  26.    leads us to the big question in the sky,  "What is sauce?"   SAUCE
  27.    is a universal process to incorporate  a  full description for any
  28.    type of file.  The most outstanding aspect of this concept is that
  29.    you have access to the complete file name,  the file's title,  the
  30.    creation date, the creator of the file, the group that the creator
  31.    is employed by, and much, much, more.
  32.  
  33.         Let us begin with a description  of  the record layouts used.
  34.    The record layouts and code  examples  are  in  a  variated pascal
  35.    pseudo code, and should  be  transferrable  enough to implement in
  36.    most  other  programming  languages.  For  ease  of  reading,  the
  37.    examples assume  that  the  file  is  correct  and  that no error-
  38.    checking need be included.  How  rigorous  you check for errors is
  39.    completely up to you, and will most likely depend on the file type
  40.    you are describing.
  41.  
  42.  
  43.    SAUCE RECORD
  44.    ------------
  45.  
  46.         This portion of the documentation  is about the SAUCE record.
  47.    The SAUCE record describes the  file  in short, and provides other
  48.    information not included in the SAUCE record itself.
  49.  
  50.    A sauce record is _EXACTLY_ 128 bytes in size.
  51.  
  52.    Fieldname   : Name of the field.
  53.    Size        : Size of the field in BYTES
  54.    Type        : Type of data. This can be :
  55.      BYTE      : One byte unsigned numeric value (0 to 255)
  56.      WORD      : Two byte unsigned numeric value (0 to 65535)
  57.      INTEGER   : Two byte signed numeric value (-32768 to 32767)
  58.      LONG      : Four byte signed numeric value (-2147483648 to 2147483647)
  59.      CHARACTER : One byte ASCII value.  Longer character fields are
  60.                  padded with spaces.  It is _NOT_ a PASCAL string (with a
  61.                  leading length byte), and it's _NOT_ a C-Style string
  62.                  (with a trailing nul-byte).  A 10 byte character field
  63.                  holding the text 'ANSI' would look like this.
  64.                  'ANSI      '.
  65.    
  66.         Numeric fields should be zero when not used, character fields
  67.    should be all spaces when not used.
  68.    
  69.     V#          : SAUCE Version number.  This indicates the version of
  70.                   SAUCE when the field was implemented.
  71.  
  72.     Description : Complete description of the field.
  73.  
  74.  
  75.     !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  76.     No fields are REQUIRED to be filled in except for ID, Version, FileSize,
  77.     DataType and FileType.
  78.     !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  79.  
  80.     FieldName Size Type      V# Description
  81.     --------- ---- --------- -- -----------
  82.     ID          5  Character 00 SAUCE Identification. This should be equal to
  83.                                 'SAUCE' or the record is not a valid SAUCE
  84.                                 record.
  85.     Version     2  Character 00 Version number of SAUCE. Current version is
  86.                                 '00'.  As new features are added to the
  87.                                 specifications of SAUCE, this version number
  88.                                 will change.  Future versions SHOULD remain
  89.                                 compatible with version 00 only ADDING on
  90.                                 the specifications, it is however not unlikely
  91.                                 that this compatibility is impossible to
  92.                                 maintain, but this is of no concern now.
  93.     Title      35  Character 00 Title of the file.
  94.     Author     20  Character 00 Name or handle of the creator of the file.
  95.     Group      20  Character 00 Name of the group the creator is employed by.
  96.     Date        8  Character 00 Date the file was created. This date is in
  97.                                 the format CCYYMMDD (Century, year, month,
  98.                                 day).  There is a good reason why the date
  99.                                 is in this format, but it's not used in
  100.                                 version '00' of SAUCE.  It will be used in
  101.                                 a future version of SAUCE.
  102.     FileSize    4  Long      00 Original filesize NOT including any
  103.                                 information of SAUCE.
  104.     DataType    1  Byte      00 Type of Data. (See DATATYPES further on)
  105.     FileType    1  Byte      00 Type of File. (See DATATYPES further on)
  106.     TInfo1      2  Word      00 Numeric information field 1 (See DATATYPES)
  107.                                 When used, this field holds informative
  108.                                 values.  Any program using SAUCE should not
  109.                                 rely on these values being correct or filled
  110.                                 in.
  111.     TInfo2      2  Word      00 Numeric information field 2 (See DATATYPES)
  112.     TInfo3      2  Word      00 Numeric information field 3 (See DATATYPES)
  113.     TInfo4      2  Word      00 Numeric information field 4 (See DATATYPES)
  114.     Comments    1  Byte      00 Number of Comment lines (See COMMENTS)
  115.     Flags       2  Word    * 00 Flags indication optional settings/switches
  116.                                 These flags have different meaning depending
  117.                                 on the data type.
  118.                                 The flags weren't originally in the concept
  119.                                 for Version 00 of SAUCE. but since the
  120.                                 specification of SAUCE expects all filler
  121.                                 bytes to be binary zero, the flags should be
  122.                                 set to ZERO in all previous files, and cause
  123.                                 no significant harm.
  124.  
  125.  
  126.     An Example PASCAL record looks like this:
  127.  
  128.       TYPE SAUCERec = RECORD
  129.                         ID       : Array[1..5] of Char;
  130.                         Version  : Array[1..2] of Char;
  131.                         Title    : Array[1..35] of Char;
  132.                         Author   : Array[1..20] of Char;
  133.                         Group    : Array[1..20] of Char;
  134.                         Date     : Array[1..8] of Char;
  135.                         FileSize : Longint;
  136.                         DataType : Byte;
  137.                         FileType : Byte;
  138.                         TInfo1   : Word;
  139.                         TInfo2   : Word;
  140.                         TInfo3   : Word;
  141.                         TInfo4   : Word;
  142.                         Comments : Byte;
  143.                         Flags    : Byte;
  144.                         Filler   : Array[1..22] of Char;
  145.                       END;
  146.  
  147.     An Example C record looks like this:
  148.  
  149.       typedef SAUCEREC {
  150.          char          ID[5];
  151.          char          Version[2];
  152.          char          Title[35];
  153.          char          Author[20];
  154.          char          Group[20];
  155.          char          Date[8];
  156.          signed long   FileSize;
  157.          unsigned char DataType;
  158.          unsigned char FileType;
  159.          unsigned int  TInfo1;
  160.          unsigned int  TInfo2;
  161.          unsigned int  TInfo3;
  162.          unsigned int  TInfo4;
  163.          unsigned char Flags;
  164.          char          Filler[22];
  165.       } SAUCEREC;
  166.  
  167.  
  168.     DATATYPES
  169.     ---------
  170.         DataType and FileType hold the information needed to deter-
  171.     mine what type of file it is.
  172.  
  173.     There are 5 DataTypes, these are (with their respective numeric values) :
  174.       0) None      : Undefined filetype, you could use this to add SAUCE
  175.                      information to personal datafiles needed by programs,
  176.                      but not having any other meaning.
  177.       1) Character : Any character based file.  Examples are ASCII, ANSi and
  178.                      RIP.
  179.       2) Graphics  : Any bitmap graphic file.  Examples are GIF, LBM, and
  180.                      PCX.
  181.       3) Vector    : Any vector based graphic file.  Examples are DXF and
  182.                      CAD files.
  183.       4) Sound     : Any sound related file.  Examples are samples, MOD
  184.                      files and MIDI.
  185.       5) BinaryText: This is RAW memory copy of a text screen.  It's
  186.                      basically the BIN format you can save from whitin
  187.                      TheDraw.  Each character is built up of two consecutive
  188.                      bytes.  The first is the character to be displayed.  The
  189.                      second is the Attribute byte.
  190.  
  191.  
  192.      None
  193.      ----
  194.      When using the 'None' datatype, you should have FileType set to
  195.      zero also.  This is a compatibility issue as it's not unlikely,
  196.      the 'None' datatype will have filetypes in the future.
  197.  
  198.      Character
  199.      ---------
  200.      When using the 'Character' datatype, you have following filetypes
  201.      available :
  202.  
  203.       0) ASCII     : Plain text file with no formatting codes or color codes.
  204.                      TInfo1 is used for the width of the file.
  205.                      TInfo2 is used to hold the number of lines in the file.
  206.       1) ANSi      : ANSi file.  With ANSi color codes and cursor
  207.                      positioning.
  208.                      TInfo1 is used for the width of the file.
  209.                      TInfo2 is used to hold the number of ANSi screen lines
  210.                      in the file.
  211.       2) ANSiMation: ANSi Animation.  With ANSi color codes and cursor
  212.                      positioning.  While an ANSi file can also have animated
  213.                      sequences, there is a clear distinction.  While an ANSi
  214.                      may or may not have a beginning animated sequence
  215.                      introducing the group or artist the rest is just a
  216.                      sequence of colored characters.  An ANSiMation on the
  217.                      other hand is a more like a text mode cartoon.
  218.                      TInfo1 is used for the width of the file.
  219.                      TInfo2 is used to hold the number of ANSi screen lines
  220.                      the ANSiMation was created for.
  221.                      A program using SAUCE may use these two values to
  222.                      switch to the appropriate video mode.
  223.       3) RIP       : Remote Imaging Protocol (RIP) graphics file.
  224.                      TInfo1 holds the width (should be 640)
  225.                      TInfo2 holds the height (should be 350)
  226.                      TInfo3 holds the number of colors (should be 16)
  227.       4) PCBoard   : File with PCBoard style @X color codes and @ macro's
  228.                      and ANSi codes.
  229.                      TInfo1 is used for the width of the file.
  230.                      TInfo2 is used to hold the number of ANSi screen lines
  231.                      in the file.
  232.       5) AVATAR    : A file with AVATAR and ANSi color codes and cursor
  233.                      positioning.
  234.  
  235.       FLAGS for the Character Datatype.
  236.       -----
  237.       ┌─ 7 ─┬─ 6 ─┬─ 5 ─┬─ 4 ─┬─ 3 ─┬─ 2 ─┬─ 1 ─┬─ 0 ─┐
  238.       │     │     │     │     │     │     │     │     │
  239.       │  0  │  0  │  0  │  0  │  0  │  0  │  0  │  A  │
  240.       │     │     │     │     │     │     │     │     │
  241.       └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
  242.  
  243.       All non-used bits should be ZERO.
  244.  
  245.       A) Non-Blink mode (iCE Color).
  246.          When this bit is SET (equal to 1) The ANSi is created using iCE
  247.          color codes.  This is a special mode where the blinking is
  248.          disabled, and you have 16 background colors available.  Basically,
  249.          you have the same choice for background colors as for foreground
  250.          colors.
  251.  
  252.          Please note:
  253.  
  254.          When the picture does not make specific use of the iCE color, you
  255.          should NOT have this bit set.  When you do not support the iCE
  256.          color mode, you should probably not display the file as it could
  257.          look pretty weird in normal mode.
  258.  
  259.      Graphics
  260.      --------
  261.      For all graphics types, TInfo1 holds width of the image, TInfo2
  262.      holds the Height of the image and TInfo3 holds the number of bits
  263.      per pixel (a 256 colour image would have 8 bits per pixel, a
  264.      TrueColor image would have 24);
  265.  
  266.      Following Graphics filetypes are available :
  267.  
  268.      0) GIF     (CompuServ Graphics Interchange format)
  269.      1) PCX     (ZSoft Paintbrush PCX format)
  270.      2) LBM/IFF (DeluxePaint LBM/IFF format)
  271.      3) TGA     (Targa Truecolor)
  272.      4) FLI     (Autodesk FLI animation file)
  273.      5) FLC     (Autodesk FLC animation file)
  274.      6) BMP     (Windows Bitmap)
  275.      7) GL      (Grasp GL Animation)
  276.      8) DL      (DL Animation)
  277.      9) WPG     (Wordperfect Bitmap)
  278.     10) SBM     (SUN BitMap)
  279.     11) JPG     (JPeg compressed File)
  280.     12) MPG     (MPeg compressed animation/video)
  281.     13) AVI     (Audio Visual Interlace)
  282.  
  283.      FLAGS
  284.      -----
  285.      Not used, should be all zeroes.
  286.  
  287.      Vector
  288.      ------
  289.      Following Vector filetypes are available :
  290.      0) DXF     (CAD Data eXchange File)
  291.      1) DWG     (AutoCAD Drawing file)
  292.      2) WPG     (WordPerfect/DrawPerfect vector graphics)
  293.      3) SVI     (Sun VectorImage)
  294.  
  295.      FLAGS
  296.      -----
  297.      Not used, should be all zeroes.
  298.  
  299.      Sound
  300.      -----
  301.      Following sound filetypes are available :
  302.      0)  MOD    (4, 6 or 8 channel MOD/NST file)
  303.      1)  669    (Renaissance 8 channel 669 format)
  304.      2)  STM    (Future Crew 4 channel ScreamTracker format)
  305.      3)  S3M    (Future Crew variable channel ScreamTracker3 format)
  306.      4)  MTM    (Renaissance variable channel MultiTracker Module)
  307.      5)  FAR    (Farandole composer module)
  308.      6)  ULT    (UltraTracker module)
  309.      7)  AMF    (DMP/DSMI Advanced Module Format)
  310.      8)  DMF    (Delusion Digital Music Format (XTracker))
  311.      9)  OKT    (Oktalyser module)
  312.      10) ROL    (AdLib ROL file (FM))
  313.      11) CMF    (Creative Labs FM)
  314.      12) MIDI   (MIDI file)
  315.      13) SADT   (SAdT composer FM Module)
  316.      14) VOC    (Creative Labs Sample)
  317.      15) WAV    (Windows Wave file)
  318.      16) SMP8   (8 Bit Sample, TInfo1 holds sampling rate)
  319.      17) SMP8S  (8 Bit sample stereo, TInfo1 holds sampling rate)
  320.      18) SMP16  (16 Bit sample, TInfo1 holds sampling rate)
  321.      19) SMP16S (16 Bit sample stereo, TInfo1 holds sampling rate)
  322.      20) PATCH8 (8 Bit patch-file)
  323.      21) PATCH16(16 Bit Patch-file)
  324.  
  325.      FLAGS
  326.      -----
  327.      Not used, should be all zeroes.
  328.  
  329.      BinaryText
  330.      ----------
  331.      The Binary Text format, basically has no Filetype, since the datatype
  332.      has already defined how the file will look.
  333.      The FileType however specifies the WIDTH of the BinaryText screen.
  334.      Only the Width is required, as the Height can be calculated by dividing
  335.      the filesize by the Width.
  336.      In an attempt to provide as much WIDTH as possible in a possible 256
  337.      values of the Byte-sized FileType.  The width is specified in Multiples
  338.      of 2.  The fact that the Width is specified in multiples of 2 isn't
  339.      really a problem, since you also need to define the effective screen
  340.      size in multiples of 2.
  341.  
  342.      An example : For normal 80*25 binary images as made with TheDraw the
  343.                   FileType value would be 40 (since 2*40 equals 80 <g>)
  344.                   All you need to do is divide the width of the binary text
  345.                   image by 2. This gives a maximum width of 510 characters.
  346.                   Although currently not supported, should there be a need
  347.                   for even bigger images, this can be arranged.
  348.  
  349.      Please note.  BinaryText expects the character-attribute pairs to be
  350.      stored one row at a time.  If you wanted to create a 80*100 Image, you
  351.      could do this by just copying 4 80*25 or 2 80*50 together to form one
  352.      bigger image.
  353.      If for example you wanted to create a 160*25 image from 2 80*25 images,
  354.      you would need to write a little program which would copy line 1 from
  355.      image 1, line 1 from image 2, Line 2 from Image 1, Line 2 from Image 2
  356.      and so on.
  357.      Basically, you should have all character-attribute pairs from one line
  358.      of the COMPLETE image one after the other, followed by all
  359.      char-attribute pairs from the next row, and so on.
  360.  
  361.      If the picture does not fit this format. You should use the NONE
  362.      datatype.  Besides.  you'd probably want to have it in this format
  363.      anyway, as it seems to be the most logical approach to have these kind
  364.      of images.
  365.  
  366.       FLAGS for the BinaryText Datatype.
  367.       -----
  368.       ┌─ 7 ─┬─ 6 ─┬─ 5 ─┬─ 4 ─┬─ 3 ─┬─ 2 ─┬─ 1 ─┬─ 0 ─┐
  369.       │     │     │     │     │     │     │     │     │
  370.       │  0  │  0  │  0  │  0  │  0  │  0  │  0  │  A  │
  371.       │     │     │     │     │     │     │     │     │
  372.       └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
  373.  
  374.       All non-used bits should be ZERO.
  375.  
  376.       A) Non-blink mode (iCE Color).
  377.          This bit has exactly the same meaning as for the Character
  378.          datatype.  It indicates whether the picture uses iCE color.
  379.  
  380.  
  381.     COMMENTS
  382.     --------
  383.         The  comment  block  is an addition to the SAUCE  record.  It
  384.     holds up to  255  lines of additional information.  Each  line 64
  385.     characters wide.
  386.  
  387.         When the Comments field is not  zero,  it holds the number of
  388.     additional comment lines are available.  A single comment line is
  389.     64 characters  long.  Like  the character  fields  in  the  SAUCE
  390.     record, it is padded with spaces,  and has no leading length byte
  391.     or trailing null-byte.
  392.  
  393.         The comment block is  preceded  with  a 5 character identifi-
  394.     cation mark.  This identification mark is 'COMNT'.
  395.  
  396.  
  397.     SAUCE IN FILES
  398.     --------------
  399.         A file with SAUCE added to it.  Will look like this:
  400.  
  401.      ┌───────────────┐
  402.      │               │
  403.      │   FILE DATA   │  Actual file data.  As if it would be without SAUCE.
  404.      │               │
  405.      ├───────────────┤
  406.      │               │
  407.      │  EOF MARKER   │  EOF marker.  This will assure character files can
  408.      │               │  easily determine the end of file.
  409.      ├───────────────┤
  410.      │               │
  411.      │ COMMENT BLOCK │  Optional Comment block.
  412.      │               │
  413.      ├───────────────┤
  414.      │               │
  415.      │ SAUCE RECORD  │  SAUCE record.
  416.      │               │
  417.      └───────────────┘
  418.  
  419.  
  420.     The Comment block
  421.  
  422.      ┌───────────────┐
  423.      │               │
  424.      │   'COMNT'     │  Comment block ID bytes
  425.      │               │
  426.      ├───────────────┤
  427.      │               │
  428.      │ COMMENTLINE 1 │  First comment line
  429.      │               │
  430.      ├───────────────┤
  431.      │               │
  432.      │ COMMENTLINE 2 │  Second comment line
  433.      │               │
  434.      ├───────────────┤
  435.      ...
  436.      ├───────────────┤
  437.      │               │
  438.      │ COMMENTLINE N │  n-th comment line, n equals the Comments field
  439.      │               │  in SAUCE record.
  440.      └───────────────┘
  441.  
  442.  
  443.  
  444.     EXAMPLE CODE TO READ SAUCE
  445.     --------------------------
  446.     Variables:
  447.       Byte : Count;
  448.       Long : FileSize;
  449.       file : F;
  450.  
  451.     Code:
  452.       Open_File(F);                         | Open the file for read access
  453.       FileSize = Size_of_file(F);           | Determine filesize
  454.       Seek_file (F, FileSize-128);          | Seek to start of SAUCE (Eof-128)
  455.       Read_File (F, SAUCE);                 | Read the SAUCE record
  456.       IF SAUCE.ID="SAUCE" THEN              | ID bytes match "SAUCE" ?
  457.          IF SAUCE.Comments>0 THEN           | Is there a comment block ?
  458.             Seek_File(F, FileSize-128-(SAUCE.Comments*64)-5);
  459.                                             | Seek to start of Comment block.
  460.             Read_File(F, CommentID);        | Read Comment ID.
  461.             IF CommentID="COMNT" THEN       | Comment ID matches "COMNT" ?
  462.                For Count=1 to SAUCE.Comments| \ Read all comment lines.
  463.                   Read_File(F, CommentLine) | /
  464.                ENDFOR
  465.             ELSE
  466.                Invalid_Comment;             | Non fatal, No comment present.
  467.             ENDIF
  468.          ENDIF
  469.       ELSE
  470.          Invalid_SAUCE;                     | No valid SAUCE record was found.
  471.       ENDIF
  472.  
  473.  
  474.     SAUCE DATAFILE
  475.     --------------
  476.     The full specifications of the SAUCE datafile are not ready yet.
  477.  
  478.  
  479.     INFORMATION OR UPGRADES
  480.     -----------------------
  481.         If you have a need for additional information on SAUCE, or
  482.     need modifications, you can contact me at these places...
  483.  
  484.     Leave a message to TASMANIAC :
  485.  
  486.     Neo Tokyo       +32-50-620112   USR 28800 Dual
  487.                     +32-50-625717   ZyXEL 19200
  488.  
  489.     or contact SiDS at bmorin@wpi.edu
  490.  
  491.