pouët.net

PSYCHOSE Inc. Demomaker Kit.

                                  
 ╔══════════════════════════════════════════════════════════════════════════╗
 ║              P S Y C H O S E   D A T A   F I L E   M A K E R             ║
 ║                                    &                                     ║
 ║      P S Y C H O S E   D A T A   F I L E   I N T E R F A C E   K I T     ║
 ║                                                                          ║
 ║                     for Assembly language programming                    ║
 ╟──────────────────────────────────────────────────────────────────────────╢
 ║                                                                          ║
 ║      This is the documentation file for the Psychose Datafile Maker      ║
 ║                and for the Psychose Datafile Interface Kit               ║
 ║                                                                          ║
 ║                     -=≡≡≡ P D F M  &  P D F I K ≡≡≡=-                    ║
 ║                                                                          ║
 ╟──────────────────────────────────────────────────────────────────────────╢
 ║             (C)opyright 1993 by NAPALM from PSYCHOSE, Inc.               ║
 ╚══════════════════════════════════════════════════════════════════════════╝






                    = ] ------ Table of contents ------ [ =


  1. [Introduction] ........... Hey...ya! What is the PDFM ?
  2. [License] ................ Yep yep ! Don't forget it dude...
  3. [A matter of food] ....... How to feed this 'byte-eater' utility.
  4. [Related stuff: PDFIK] ... Whoa! Cool! But what now ?
  5. [PDFIK functions] ........ At last! Calling PDFIK from assembly.
     5.1 What you need to include in your source code
     5.2 Calling conventions
  6. [To contact me] .......... BBS, Minitel and all that.
  7. [Good bye user] .......... Latest information.


                    = ] ------------------------------- [ =




 


  1. [Introduction]

     The PSYCHOSE Datafile Maker (PDFM) is a small utility designed to help
     you create special files, called datafiles, where you put all the
     data (such as images, musics or texts ) you need for a demo.
     The original data is compressed using a standard Lempel-Ziv algorithm
     which can achieve good compression ratios, saving space (and also disks
     when it's time to release your demo...).
     Even if this is supposed to be a standard utility, you'll need at least
     a 386 to run this program, because I used several 386 instructions
     during coding. (I know what ya're goin' to tell me but forget it !!!)




  2. [License]

     You are free to use, distribute or copy PDFM and PDFIK, but only under
     the following conditions:

     ■ The program using PDFM and PDFIK is not a commercial one
       (Shareware is considered as commercial software)

     ■ You must mention in your program and/or in its documentation
       you used PDFM and/or PDFIK, that is give us credits for the work
       we've done!

     ■ PDFM and PDFIK are not modified in any way, and stay in their
       original form. If you decide to copy PDFM and PDFIK to a friend
       (and you are encouraged to do so...), please copy the full package
       with its documentation, include and executable files.




  3. [A matter of food]

     You'll have to provide the PDFM with a Listfile, that is, a file
     containing the name of the Datafile (were the packed data is stored)
     and the names of the files you want to include in that Datafile.
     The Listfile is an ASCII file organized as follows:

     ┌────────────┐
     │DATANAME.EXT│ <───■ Datafile name (MUST be the first one...)
     │FILE1.EXT   │ <───■ File name n°1
     │FILE2.EXT   │ <───■ File name n°2
     │    .       │
     │    .       │
     │    .       │
     │FILEn.EXT   │ <───■ The last file name
     │∞           │ <───■ [ALT 236] character for 'end of input'
     └────────────┘

     note: there must be only one name per line.




  4. [Related stuff: PDFIK]

     The Datafile is nice, isn't it dear ? wha ah ah ah ah! ...hum...
     So now you got a Datafile ready but a simple question flashed through
     your mind...: Hey Dude! How do I use the Datafile from my source code ?
     Well...er... PSYCHOSE is here again to help you!
     I coded a special interface called PSYCHOSE Datafile Interface Kit
     (PDFIK) which implements cool functions for lazy loading of a specified
     file from the Datafile (where it's stored...) into a memory buffer.
     This lazy interface offers full support of 32BMM (another cool OBJ from
     ...? Guess who...? PSYCHOSE evidently...)
     See the next section for more precise details.




  5. [PDFIK functions]

     Remember you must have at least a 386 to run any of these routines!
     and when using .386P or .486 directives don't forget to specify
     the USE16 directive in segment(s) declaration(s).
     (besides the functions will not test any of these for you...)


     5.1 What you need to include in your source code

         just insert the following line in your code:
         include PDFIK.INC

         The PDFIK.INC file contains the necessary declarations and
         data stuctures to communicate with the PDFIK.
         Here is a copy of its contents:

         EXTRN PDFIK_ASM : FAR   ; Main routine (external)

         PARAM_STRUC     STRUC   ; Structure to pass & receive parameters
         Function        db ?    ; Function number
         DtaSeg          dw ?    ; Segment of related datas
         DtaOfsPdf       dw ?    ; Offset in DtaSeg of datafile name (ASCIIZ)
         DtaOfsFil       dw ?    ; Offset in DtaSeg of file name     (ASCIIZ)
         OfsInPdf        dd ?    ; Offset from beginning of Datafile
         OfsInFil        dd ?    ; Offset from beginning of File
         NumBytes        dd ?    ; Number of bytes to decompress
         BufSeg          dw ?    ; Segment of buffer where to unpack the data
         BufOfs          dw ?    ; Offset in BufSeg
         FlatMode        db ?    ; 0=No 32BMM, 1=32BMM use/compatible.
         MemMode         db ?    ; Memory mode of output buffer (see 32BMM ref.)
         MemHandle       dw ?    ; Handle of output buffer (32BMM support)
         LinearOfs       dd ?    ; 32bit linear offset of output buffer (32BMM)
         NormSize        dd ?    ; Size of the normal file (unpacked)
         PackSize        dd ?    ; Size in the datafile (packed)
         ErrorCode       db ?    ; Return code from PDFIK
         PARAM_STRUC     ENDS    ; End of structure

         I think all the fields are self-explanatory (Ok, Ok I'm the coder
         so it's normal no?) except perhaps the OfsInPdf field.
         This field is used when the Datafile is integrated in the EXE,
         that is when you (and everyone for sure!) want the Datafile to be
         part of the EXE file, so that you release only one (Big!) EXE.
         This 32 bit number represents the size of the EXE just after
         compile process is complete. To include the Datafile in the EXE just
         type:  COPY /B PROG.EXE+DATAFILE.EXT NEWPROG.EXE
         and remember to use the 'NEWPROG.EXE' filename for the DtaOfsPdf
         field (that is, as the Datafile name!).

         coder's advice:
         You don't need to set up all the fields each time you call one
         function (this will lead to a real nightmare! huhu...).
         In fact fill the "general purpose" fields in some initilization
         routine at the beginning of yar program and then you just have to fill
         3 or 4 fields at each call (unless ya wanna change some settings!).


     5.2 Calling conventions

         Please refer to the 32BMM reference for detailed explanations about
         the fields referencing use of 32BMM.

         We assume here that the 'x' label refers to a PARAM_STRUC type
         structure declared and allocated in your Data Segment as follows:
         x      PARAM_STRUC <,,,,,,,,,>

         At this moment only three functions are available. The first one is
         called [GetInfo] and is used to obtain information (i.e: the size
         of the original file, and its size in the Datafile) about a specified
         file stored in the Datafile. The second function is [Extract] and...
         huhu... is used to extract a file from the Datafile to a memory
         buffer. The third one is [Extract2] and provides the laziest loading
         of a file because it takes less parameters and allocates directly
         the memory (which has to be de-allocated by user..).
         You can call the three routines like this:

         mov x.Function,(Function number)
             ...
         <Fill all necessary fields>
             ...
         mov ES,(Segment of x)
         mov BX,(Offset of x)
         call PDFIK_ASM
         <Check the return code>


         [GetInfo routine]
         ■ before call:
           x.Function  = 0
           x.DtaSeg    = Address of DATA segment (for following datas)
           x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
                         (string example:  Datafile db 'DATA1.DTA',0 )
           x.DtaOfsFil = Offset of ASCIIZ string for file name
                         (string example:  File db 'TEXT.DOC',0 )
           x.OfsInPdf  = Offset for beginning of Datafile in EXE
                         (i.e: size of the EXE file)
                         This value is 0 when Datafile is not integrated
                         in a EXE.
           ES:BX       = pointer to the x structure (PARAM_STRUC type)


         ■ after call:
           x.NormSize  = Size of original file (for memory allocation)
           x.PackSize  = Size of packed file
           x.ErrorCode = return code from PDFIK
                         0 = OK, no problemo!
                         1 = Datafile not found (wrong name, ...)
                         2 = Invalid format (not a PSYCHOSE Datafile)
                         3 = File not found in Datafile (wrong name, ...)
                         4 = Memory allocation error (used by [Extract2])
           ES:BX       = pointer to the x structure (PARAM_STRUC type)



         [Extract routine]
         ■ before call:
           x.Function  = 1
           x.DtaSeg    = Address of DATA segment (for following datas)
           x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
                         (string example:  Datafile db 'DATA1.DTA',0 )
           x.DtaOfsFil = Offset of ASCIIZ string for file name
                         (string example:  File db 'TEXT.DOC',0 )
           x.OfsInPdf  = Offset for beginning of Datafile in EXE
                         (i.e: size of the EXE file)
                         This value is 0 when Datafile is not integrated
                         in a EXE.
           x.BufSeg    = Segment of buffer where we unpack
                         (allocated by user)
           x.BufOfs    = Offset in BufSeg
           ES:BX       = pointer to the x structure (PARAM_STRUC type)


         ■ after call:
           x.ErrorCode = return code (see GetInfo)
           ES:BX       = pointer to the x structure (PARAM_STRUC type)



         [Extract2 routine - 32BMM compatible]
         ■ before call:
           x.Function  = 2
           x.DtaSeg    = Address of DATA segment (for following datas)
           x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
                         (string example:  Datafile db 'DATA1.DTA',0 )
           x.DtaOfsFil = Offset of ASCIIZ string for file name
                         (string example:  File db 'TEXT.DOC',0 )
           x.OfsInPdf  = Offset for beginning of Datafile in EXE
                         (i.e: size of the EXE file)
                         This value is 0 when Datafile is not integrated
                         in a EXE.
           x.OfsInFil  = Offset from which we begin to unpack
                         (i.e: how many bytes we jump in the original
                          file before unpacking)
           x.NumBytes  = How many bytes we unpack
                         (0 means unpack ALL)
           x.FlatMode  = 0 means standard DOS memory allocation
                         1 means 32BMM Flat Real Mode memory allocation
           ES:BX       = pointer to the x structure (PARAM_STRUC type)


         ■ after call:
           x.ErrorCode = return code (see GetInfo)
           if x.FlatMode was 1
                x.LinearOfs = 32bits linear address of output buffer
                x.MemMode   = Memory mode of output buffer (Save it!)
                x.MemHandle = Handle of output buffer (Save it!)
           else
                x.BufSeg    = Segment of output buffer
           ES:BX       = pointer to the x structure (PARAM_STRUC type)

           Note: this is very easy to convert a standard segment to a 32bits
                 linear address compatible with 32BMM. Just multiply the
                 segment value by 16 and you'll get it ! For example if AX
                 contains the segment value, ESI will contain the 32bits linear
                 address after the follwing lines:

                        movzx esi,ax
                        shl esi,4
                        ...




  6. [To contact me]  (Hey! no illegal stuff ok?)

     If you're French use your Minitel:
       3615 RTEL
       BAL NAPALM
     (alors les p'tits gars ça flotte ? Hehe...)

     For a personal contact write to:

                             ┌───────────────────────┐
                             │ Rémy Chibois (NAPALM) │
                             └───────────┬───────────┘
         ┌──────────────────────────┐    │    ┌───────────────────┐
         │   1 ter Av. de l'étang   │<───┴───>│ 43 rue de Chabrol │
         │ 78320 Le Mesnil St Denis │         │    75010 Paris    │
         │          FRANCE          │         │      FRANCE       │
         └──────────────────────────┘         └───────────────────┘




  7. [Good bye user]

     I intend to improve the compression algorithm, of course, and new
     functions will also be added to ensure a more flexible use.
     (is that possible ?  Haha..)
     Well now you're on your own, and I wish this utility will be usefull
     to you.
     Please don't make lame with this utility and give us the credits we
     deserve if you decide to use this program.
     You can send me your demos if you're pleased with PDFM & PDFIK !!
     Have a pleasant coding.