TAJGA 2D graphic library
Windows DirectDraw platform documentation

TABLE OF CONTENTS
=================
0 - About Windows DirectDraw platform
1 - Defines
2 - Data
  2.1 - os.hinst
  2.2 - os.ddraw
  2.3 - os.surf
  2.4 - os.surfdesc
  2.5 - os.hwnd
  2.6 - os.class
  2.7 - os._class
  2.8 - os.class.present
  2.9 - os.curcooplvl
  2.10 - os.cooplvl

1 - Defines
===========
TODO - 
 TODO - symbol which must be defined

2 - Data
  All variables are zeroed by os.Init

  INTERNAL here means there is no reason for user to access this variable.

  2.1 - os.hinst
  ==============
    handle to instance.
    After initializing TG2D contains handle to instance

    modified by
      - os.Init - fills it from GetModuleHandle

  2.2 - os.ddraw
  ==============
    directdraw object handle (LPDIRECTDRAW). Contains 0 if directdraw object
    isn't obtained.
    
    modified by:
      - os.AccessOriginalMode - via CreateDirectDraw if not obtained yet
      - os.SetVideoMode - via CreateDirectDraw if not obtained yet
      - os.Close - released (and zeroed) if is obtained
  
  2.3 - os.surf
  =============
    primary surface handle (LPDIRECTDRAWSURFACE). Contains 0 if not obtained
    yet.

    modified by:
      - os.AccessOriginalMode 
      - os.SetVideoMode
      - os.ResetVideoMode
      - os.Close - released (and zeroed) if is obtained

  2.4 - os.surfdesc
  =================
    static structure DDSURFACEDESC. Valid when "os.surf" is nonzero.

    modified by:
      - os.AccessOriginalMode
      - os.SetVideoMode
      - os.ResetVideoMode
    notes:
      - there is possiblity that data in structure isn't valid even when
        "os.surf" doesn't contain zero. If error occured during filling
        structure. But due to DirectDraw documentation such error shouldn't
        occur.

  2.5 - os.hwnd
  =============
    handle to application window. When contains 0 then there is no window.

    modified by:
      - os.SetVideoMode - window created (see os.SetVideoMode description)
      - os.ResetVideoMode - window destroyed
      - os.Close - window destroyed if not yet

  2.6 - os.class
  ==============
    static WNDCLASS structure.

  2.7 - os._class
  ===============
    static ASCIIZ string "TG2D window class" ,name of class used for
    "os.class.lpszClassName".

  2.8 - os.class.present
  ======================
    byte boolean determining whether class is registered. When contains 0
    class is not registered, when contains nonzero value class is registered.

    modified by:
      - os.SetVideoMode - class registered
      - os.ResetVideoMode - class unregistered
      - os.Close - class unregistered

  2.9 - os.curcooplvl
  ===================
    determines current cooperative level. 0 means no cooperative level.

    modified by:
      - os.AccessOriginalMode
      - os.SetVideoMode
      - os.ResetVideoMode
      - os.Close
  
  2.10 - os.cooplvl
  =================
    allows explicit setting of cooperative level for next procedure which
    chanes it. When contains 0 procedure sets it's default cooperative level.

    used by:
      - os.AccessOriginalMode - default = DDSCL_NORMAL (value 8)
      - os.SetVideoMode - default = DDSCL_FULLSCREEN | DDSCL_EXCLUSIVE 
        (value 11h)
      - os.ResetVideoMode - default = DDSCL_NORMAL (value 8)
    notes:
      - zeroed by every procedure that uses it.
      - zeroed by os.Init

? - Procedures
  These are implementation details of procedures for current os-access.
  General information is in general documentation.  I try to describe
  functionality of module's procedures enough to nobody needs to look at
  source code.

  Possible errors returned are listed in general documentation.

  ?.1 - os.memalloc
  =================      
    functionality
      - allocates memory using GlobalAlloc with GMEM_FIXED
    errors
      TG2D_ERROR_OUTOFMEMORY (value 8)
      + Windows errors

  ?.2 - os.memfree
  =================
    functionality
      - frees memory using GlobalFree
    errors
      + Windows errors

  ?.3 - os.Init
  =============
    functionality:
      - Obtains handle of process
    errors:
      + Windows errors

  ?.4 - os.Close
  ==============
    functionality:
      - destroys application window if still exists
      - unregisters window class if registered
      - releases primary surface if existing
      - resets cooperative mode to normal (if not)
      - releases directdraw if obtained
    errors:
      + DirectDraw errors
      + Windows errors

  ?.5 - os.AccessOriginalMode
  ===========================
  
  ?.6 - os.SetVideoMode
  =====================
    functionality
      - releases actual primary surface if obtained
      - registers application window class if not yet 
        - Window procedure set by tg2d.os.wndproc (if 0 then
          tg2d.os.defwndproc used)
      - creates application window;
        - style = WS_POPUP | WS_VISIBLE; exstyle = 0
        - coords = 0,0; size = 0,0
        - name = tg2d.os.wndname (default set to point to "TG2D")
      - obtains directdraw object interface v1
      - sets ddraw cooperative level by tg2d.os.cooplvl (0 = default =
        DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN)
      - sets desired display mode
      - creates primary surface
        - flags: DDSD_CAPS
        - caps: DDSCAPS_PRIMARY
      - gets it's description to tg2d.os.surfdesc
      - sets variables
        - videobitmap.flags = CLIP
        - videobitmap.clip* = visible region        
        - vbflags = PRESENT, MUSTBELOCKED
    notes:
      - sets tg2d.os.cooplvl back to 0
    errors:
      TG2D_ERROR_UNSUPPORTEDMODE (value 7)
      + Windows errors
      + DirectDraw errors
  
  ?.7 - os.ResetVideoMode
  =======================
    functionality
      -

  ?.8 - os.Lock
  =============
    
  ?.9 - os.Unlock
  ===============

  ?.10 - os.Retrace
  ================

vim: tw=78 expandtab
