This file contains help about FFD-files,which are used in WAVCAP.

**********************************************
*  File Format descriptor - help  (FFD-help) *
**********************************************


       1        What is File format descriptor ?
         1.1    Naming...
       2.1      Creating - theoretical point of view
       2.2      Creating - practical point of view


1.        File Format Descriptor is a module , which
          describes some file format.
      For example:  Descriptor for WAVes (files with WAV-extension
      or in other words it is SOUND) is module , which will be loaded
      when you'll press enter on some WAV-file in WAVCAP and which will
      be used to read this WAV-file.

      1.1       Naming:
              Every FFD-file must have name:  FFD_???.PLG
              , where ??? is your extension.
      Example:     for WAV : FFD_WAV.PLG
                   for VOC : FFD_VOC.PLG
                   for ZZZ : FFD_ZZZ.PLG

2.1    Creating - theoretical point of view
******************
*  GetInfo       *
******************

*       Ok - your module is loaded and gets control...
*       You got Filename , from where current file has been captured
*       from in FromFile  (You may use lds,dx FromFile)
*       You got info at which position it is located in CurFile-struct...

fname    DB 13 dup (?)      <- here are filename - no need for us...
fattr    DB ?               <- attributes - who cares...
fsize    DD ?               <- filesize...  - hmmm... it could be useful
                            <- may be used:
                                  lds si,CurFile
                                  mov cx,word ptr ds:[si+ToFileSize]
                                  mov dx,word ptr ds:[si+ToFileSize+2]
                                  ;Loads filesize in CX:DX - registers...
pos      DD ?               <- Position , at which our file is stored
                            <- Must be used:
                                  lds si,CurFile
                                  mov cx,word ptr ds:[si+ToPosition]
                                  mov dx,word ptr ds:[si+ToPosition+2]
                                  ;Loads position in CX:DX - registers...
*       and you'll must fill out SoundInfo - struct...
*       (May be used les di,SoundInfo)

SoundInfo struct:
   freq          DW 11025   ;standart value 11025 - so if your frequency
                            ;is 11025 - no need to fill it.
   ;For pointing may be used: ToFreq
   raw_length    DD 0       ;size of RAW-data.     MUST BE FILLED !
   ;For pointing may be used: ToRAWLength
   is_mono       DB 0       ;mono or stereo - mono = 0
                            ;                 stereo =1
   ;For pointing may be used: ToIsMono
   bits          DW 8       ;Bits in sample - may be 8 or 16
   ;For pointing may be used: ToBits

*       After you'll get info you may not close file -
*       because you'll must read RAW from there - so
*       GetRAW function will be executed for next and probably more than
*       one time.

******************
*  GetRAW        *
******************
*   Get control after GetInfo (if there wasn't any error)
*   You must get value from ReadLength,which gives you
*   info abut how many bytes you'll must read from file
   mov cx,ReadLength
*   if it is zero - you'll must close file
*   if it's not - you'll must read needed information
*   in Buffer     (lds dx,Buffer)



P.S.   Need swap up & down in some sounds ?

       lds si,Buffer
       mov cx,ReadLength
Swapping:
       mov al,byte ptr ds:[si]
       xor al,80h                     ;Up & down swapping...
       mov byte ptr ds:[si],al
       inc si
       loop Swapping




2.2      Creating - practical point of view

   First of all you must choose extension of this file -
   lets take XXX-extension for example.
   Lets copy FFD_EMP.ASM to FFD_XXX.ASM

Now...
Lets edit our file
'>' - this means original line
';' - and this means comment about it.

>seg_a           segment byte public
>assume  cs:seg_a
;I don't know what it's really means - but it is needed.   ;)

>                jumps
;Jumps directive - so linker won't panic if jump will be out of range
;If you wanna shorter code - you'll must compile TASM /M9 YOUR.ASM
>                org     100h
;Standart COM- file organization - you don't need to know it.
>ProgrammStart:
;From here our programm begins...
>                DB 'WAVCAP Plugin',1Ah
;WAVCAP plugin header. - It's suppose to have this name.
>                DW 0
;Here suppose to be offset to identification , that must be in normal
;plugins... - 0 must be here.
;P.S. You may wanna mix plugin & File Format Descriptor - then it will
;be not 0
>                DW 0
>                DW 0
>                DW 0
;Here suppose to be 3 offsets functions , that is usualy used in plugins...
;All zeroes...
>                DW offset GetInfo            ;Get info & Get RAW only !
>                DW offset GetRAW
;Offsets to our functions...
>GetInfo:
;GetInfo location.
; GetInfo.       Must retrive info about sound file
;                some useful locations:
;                   FromFile - filename or full path & filename
;                              to file, from where this file has been found
;                     P.S. If you're pressing enter in FileManager window
;                          FromFile-filename is identical to CurFile-filename
;                          and Pos (in CurFile struct) is equal to 0
;                   CurFile - struct:
;          C/C++-representation      |       Assembler representation
;----------------------------------------------------------------------
;          typedef struct{           |
;                 char fname[13];    |       fname    DB 13 dup (?)
;                 char fattr;        |       fattr    DB ?
;                 long fsize;        |       fsize    DD ?
;                 long pos;          |       pos      DD ?
;                 int  filetype;     |       filetype DW ?
;                 }                  |
>                include wcplg.inc
;Include most impotant file - plugin description...
;If you got any question - answer could be always found in there...
>                lds dx,FromFile
>                call Fopen
>                jc IO_Error
;Try to open file - this is usual routine - you must fill following block:
;   ******** SoundInfo - struct *****************
;          C/C++-representation         |    Assembler representation
;----------------------------------------------------------------------
;          typedef struct{              |
;             unsigned int freq;        |    freq         DW 0
;             unsigned long raw_length; |    raw_length   DD 11025
;             unsigned char is_mono;    |    is_mono      DB 0      (0-mono 1-stereo)
;             unsigned int bits;        |    bits         DW 8      (8/16)
;          }SOUND_DATA;                 |
;If you already know all that you need - then no need for open this file
;=> just delete this lines.
>                lds si,CurFile
>                mov cx,W ds:[si+ToPosition+2];Seek to some position -
; mov cx,word ptr ds:[si+ToPosition+2] - look in WCPLG.INC
>                mov dx,W ds:[si+ToPosition]  ;Required if there are captured files
>                mov al,SEEK_SET              ;From start of file
>                call Fseek
>                jc IO_Error
;Makes seek to position - this is needed , when file is captured ,
;and it is not from start of file , but somewhere in the middle...
;****************************************
;Here you'll must read header and fill out SoundInfo - struct
;then do
;     xor ax,ax          ;All OK !
;     retf               ;Get out from here !
;****************************************
>Unsupportedformat:
>                call Fclose                  ;Close file
>                mov ax,CantRetriveInfo       ;Error code: CantRetriveInfo
>                retf                         ;Bye bye !
;Return code for Unsupported formats...
;Then WAVCAP will give message box.
>GetRAW:
;GetRAW function.
; Used to read RAW-formatted data...
; Every sound contains RAW - data , which is a sound himself.
; Usualy you'll must simple read from file this raw...
>                mov cx,cs:[ReadLength]       ;Length , that must be readed
;Get value - how much bytes must be readed...
>                cmp cx,0                     ;into buffer
>                je CloseAndByeBye            ;If zero - must close file
;If it is a zero - then we must close all files & etc...
>                lds dx,Buffer
>                call Fread
>                jc IO_Error
;Read to buffer CX-bytes.
>                cmp ax,cx                    ;Not all bytes readed ?
>                jne IO_Error                 ;Error return !!!!!!!
;Check if all bytes has been readed...
>WellDone:
>                xor ax,ax                    ;Return code: All OK !
>                retf                         ;Bye Bye !
;All ok...
>CloseAndByeBye:
>                call Fclose                  ;Close file
>                jc IO_Error
>                xor ax,ax                    ;Return code: All OK !
>                retf                         ;Bye Bye !
;Must always close file...
>                seg_a ends
>                end     ProgrammStart
;Needs to be here...


