TAJGA 2D graphic library
general platform documentation
----------------------------------------------------------------------------------------------------

TABLE OF CONTENTS:
=================
  0 - About general platform
  1 - Defines
  2 - Data
  3 - Procedures
    3.1 - os.memalloc
    3.2 - os.memfree
    3.3 - os.Init
    3.4 - os.Close
    3.5 - os.AccessOriginalMode
    3.6 - os.SetVideoMode
    3.7 - os.ResetVideoMode
    3.8 - os.Lock
    3.9 - os.Unlock
    3.10 - os.Retrace
  4 - Error handling


0 - About general platform
==========================
  Term "platform" marks part of library which acesses operating system / 3rd
  party library.
  
  Term "general platform" marks standard for all platforms, like what
  procedures they define, way they communicate with common procedures etc.
  
  All symbols defined in platform must have "tg2d.os." prefix. I write only
  "os." in this document.
  
  Of course, some other symbols may have to be defined (system procedure
  pointers), but try to keep their number as small as possible. Do not force
  user to include something he may not want to have included (if he includes
  tg2d into his project he includes everything that tg2d includes).

  If some macros are used, then they should be purged after they aren't
  needed.
    
  Do not await that some standard library headers are included, look up
  constants in library's include files and write them as a numeric value with
  their name in comment, like:
    push 32512 ;IDI_APPLICATION
  or define them with "tg2d.os." prefix
    tg2d.os.IDI_APPLICATION = 32512
  
1 - Defines
===========
  TODO
  
2 - Data
========
  All data must be aligned (to nearest higher or equal power of 2).

3 - Procedures
==============
  You must support few platform procedures for every platform. 
  
  Errors listed are only common errors platform procedure can return. Other
  errors must returned can be only platform errors (with negative number, and
  optionaly with original error number in "tg2d.error.original")

  Platform procedure can change all general purpose registers (except ESP of
  course).

  3.1 - os.memalloc
  =================      
    Allocates memory
      
    args:
      eax = size of memory block to allocate, in bytes
    returns:
      CF = 1 on error
      eax = pointer to allocated block      
    errors:
      TG2D_ERROR_OUTOFMEMORY (value 8)
        Not enough memory. Probably you are requesting too much memory.

  3.2 - os.memfree
  ================
    Frees memory allocated by os.memalloc
    
    args:
      eax = pointer to memory block to free, returned by os.memalloc
    returns:
      CF = 1 on error
    
  3.3 - os.Init
  =============
    OS dependant part of Init. That means it initializes library's platform
    dependant internals.    

    args: none
    returns: 
      CF = 1 on error
      tg2d.screenflags filled
        
  3.4 - os.Close
  ==============
    OS dependant part of Close. It should just undo all that Init did.
    
    args: none
    returns:
      CF = 1 on error
    notes:
      - remember that library should be operable after calling Close and then
        calling Init again!
      - os.Close should be able to clean up even after tg2d error occured,
        remember this when writing other procedures!
  
  3.5 - os.AccessOriginalMode
  ==========================
    This procedure is called only when display is in original mode. It gains
    access to original mode
    
    args: none
    returns:
      CF = 1 on error
      tg2d.screen and tg2d.screenflags
    notes:
      - be sure to have tg2d.screenflags and tg2d.screen filled with valid values even on case of
        error. For example if Init failed during getting access to screen,
        flag TG2D_SCREEN_PRESENT should be clear, if it failed later flag
        should be set and tg2d.screen filled.
      - you can predict access isn't gained already (this is checked in
        AccessOriginalMode)
  
  3.6 - os.SetDisplayMode
  =======================
    This one should set display mode and fill tg2d.screen and
    tg2d.screenflags.

    args:
      ebx = x resoultion
      ecx = y resolution
      edx = bytes per pixel (bytes, not bits!)
    returns:
      CF = 1 on error
      tg2d.screen and tg2d.screenflags
    notes:
      - be sure to have tg2d.screenflags and tg2d.screen filled with valid values even on case of
        error. For example if Init failed during getting access to screen,
        flag TG2D_SCREEN_PRESENT should be clear, if it failed later flag
        should be set and tg2d.screen filled.
    errors:
      TG2D_ERROR_UNSUPPORTEDMODE (value 7)
        Mode you specified isn't supported by graphic driver / platform. No
        mode is set and you remain in original display mode. If access to mde
        was gained (via AccessOriginalMode) then it is lost.
  
  3.7 - os.ResetDisplayMode
  =========================
    This procedure should restore display changed by SetDIsplayMode to state
    it was in when Init was called (last time).

    args: none
    returns:
      CF = 1 on error
      tg2d.screenflags filled
    notes:
      - access isn't gained here, AccessOriginalMode does this. This procedure
        must clear TG2D_SCREEN_PRESENT flag in tg2d.screenflags.
      - called only when display isn't in original mode (this is checked in
        ResetDisplayMode)

  3.8 - os.Lock
  =============
    This procedure should lock screen, set flag TG2D_SCREEN_LOCKED in
    tg2d.screenflags and set tg2d.screen.bmp.

    args: none
    returns:
      CF=1 on error
    notes:
      - if locking is not required on platform, and thus
        TG2D_SCREEN_MUSTBELOCKED flag then it is enough to define label for
        procedure (It will never be called).
    
  3.9 - os.Unlock
  ===============
    This procedure should unlock screen and set flag
    TG2D_SCREEN_LOCKED in tg2d.screenflags.

    args: none
    returns: CF=1 on error
    notes:
      - if locking is not required on platform, and thus
        TG2D_SCREEN_MUSTBELOCKED flag then it is enough to define label for
        procedure (It should never be called).

  3.10 - os.Retrace
  =================
    This procedure should check vertical retrace status and return it: eax = 1
    during retrace, 0 otherwise.
    
    args: none
    returns: 
      CF=1 on error
      eax = 1 during retrace, 0 otherwise
    
4 - Error handling
==================
  This chapter describes standard used in passing errors from platform
  procedure to common procedure.

  Platform can define more error codes, called "platform error". These error
  names starts with "TG2D_ERROR_". Their values must be negative.

  When error occured in platform procedure, it must return with CF set,
  otherwise it must return with CF clear. If it returns error, eax must
  contain -1 and all error informations must be filled, so that procedure
  body will only return to interface. Values of other tg2d variables
  should too validly describe situation.

  When returning platform error (those with negative value) procedure must
  also fill "tg2d.error.nameA" and "tg2d.error.nameW" members before calling
  "tg2d.OnError".

  Platform procedure can return only some of general errors. These are listed
  in chapter 3 for each platform procedure.

vim: tw=78 expandtab
