TAJGA 2D graphic library
COMMON PART DOCUMENTATION


TABLE OF CONTENTS
=================
  0 - About common part
  1 - Defines
    1.? - Flags
    1.? - Structures
    1.?.1 - bitmap
    1.?.2 - rect
  2 - Data
  3 - Procedures
    3.1 - Library controlling
      3.1.1 - Init
      3.1.2 - Close
    3.2 - Bitmaps
      3.2.1 - CreateBitmap
      3.2.2 - FreeBitmap
    3.3 - Screen
      3.3.1 - AccessOriginalMode
      3.3.2 - SetDisplayMode
      3.3.3 - ResetDisplayMode
      3.3.4 - Lock
      3.3.5 - Unlock
      3.3.6 - Retrace
  4 - Error Handling

0 - About common part
=====================
  TODO

1 - Defines
===========

  1.? - Structures
  ================
    For all structures variable "sizeof.<structure name>" is defined.
  
    All structure names have "tg2d." (note the dot) prefix (if they arent
    aliased in interface to some other name). I write names without "tg2d." here
    for simplicity.
  
    Members are separated from structure name with dot ("."). For example full
    name to access relative address of member "xsz" in structure "bitmap" is
    "tg2d.bitmap.Xsz". Same for static structures, to access to "xsz" member
    of static structure defined with "BMP tg2d.bitmap" you use "BMP.Xsz".
  
    1.?.1 - bitmap
    ============
      This structure describes two dimensional array of pixels. All members
      are dwords.
      
      members:
        xsz, ysz (unsigned ints)
          sizes of bitmap (in pixel). Size 0 is valid, value of "bmp" member is
          then zero and bitmap is called "empty".
        
        bmp (*(pixel[][]))
          pointer to 2 dimensional array of pixels. Type (size) of pixel depends
          on "bpp" member.  Sizes of array are specified in "xsz" and "ysz"
          member. Bitmap is stored by lines, so it is "(pixel[xsz])[ysz]", or
          "array[1..Ysz] of array[1..Xsz] of pixel". If this member holds value
          0, bitmap is treated as "undefined".
        
        flags (bit[32])
          Set of flags that describe bitmap. Values are described in 1.?.1.
        
        bpp (unsigned int)
          Number of bytes per pixel (not bits!). Describes pixel in array
          pointed by "bmp" member.  Only low-order byte can be used, rest must
          be zero. 
  
        clipx, clipy, clipxsz, clipysz (unsigned ints)
          Specifies clipping region of bitmap. Clipping on bitmap is performed
          only when TG2D_BITMAP_CLIP flag is set, otherwise these members are
          ignored. Clipping rectangle cant be outside bitmap, and can't be empty
          eg:
            0 <= clipx < xsz
            0 <= clipy < ysz
            0 < clipxsz <= (xsz - clipx)
            0 < clipysz <= (ysz - clipy)
  
    1.?.3 - rect (internal)
    =====================
      TODO
  
    1.?.1 - "tg2d.bitmap.flags" values
    ==================================

      user bitmap flags - you specify them when you like

        0x00000002 - TG2D_BITMAP_CLIP
          If set, all operations on bitmap will be clipped to rectangle
          specified by ".clipx", ".clipy", ".clipxsz", ".clipysz" members. If
          flag is clear clear, these members are ignored. Set this flag only
          when you are sure clipping is required, for example flag dont have
          to be set when you are bltitting rectangle from bitmap and you are
          sure rectangle won't be out of bitmap.

      internal bitmap flags - you do not need to care about them
      
        0x80000000 - TG2D_BITMAP_INTERNAL_ONECHUNK
          Is set only on bitmaps whose header (not only pixel array) was
          allocated by tg2d.  When you pass 0 as bitmap header pointer to
          CreateBitmap, it will allocate header and pixel array in one chunk
          of memory (this is where the name comes from). So FreeBitmap should
          know how bitmap is allocated and this is what is this flag for.

2 - Data
========
  TODO
  
3 - Procedures
==============
  All common procedure names have "tg2d." prefix. I exclude it in this doc.

  3.1 - Library controlling
  =========================
  
    3.1.1 - Init
    ============
      This procedure initializes library (makes it usuable)

      args: none
      returns: 
        eax = -1 on error, otherwise undefined
        other GPRs preserved
        tg2d.screenflags filled
      notes:
        - this procedure must be called before any other procedure. Otherwise
          other procedures returns TG2D_ERROR_NOTINITIALIZED (value 1) error. 
      errors:
        TG2D_ERROR_INITIALIZED (value 2)
          this value is returned when function is called when library is
          already initialized. You are calling Init twice. You can ignore this
          error.
        + errors returned by os.Init
  
    3.1.2 - Close
    =============
      This procedure uninitializes library. After it is called, library cannot
      be used and only procedure you can call then is Init to intialize it
      again.
  
      args: none
      returns: 
        eax = -1 on errors, otherwise value is undefined
        other GPRs preserved
      notes:
        - If dislay mode was changed and wasn't restored, then it is restored
          now.
        - If screen is locked, it will be unlocked
        - Close should be able to clean up even after tg2d error occured
        - If Close returns error (except TG2D_ERROR_NOTINITIALIZED) then
          library is still initialized and you can use it. State of library
          can be determined from tg2d.screenflags.
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Procedure was called when library is not initialized. You must call
          Init before.
        + errors returned by os.Close
        + errors returned by ResetVideoMode if not in original display mode.
        + errors returned by Unlock if screen is locked when called

  3.2 - Bitmaps
  =============    

    3.2.1 - CreateBitmap
    ====================
      args:
        ebx, ecx (unsigned ints)
          sizes of bitmap to create. Value must be in range 0 to 7FFFFFFFh.
        edx (unsigned int)
          bytes per pixel of bitmap to create. Value must be in range 0 to
          0FFh
        eax (bit[])
          flags of bitmap. Only user flags are allowed here, other types of
          flags are defined by this procedure
        edi (bitmap*)
          0 or pointer to bitmap header. 
      returns:
        eax = -1 on errors, otherwise pointer to new bitmap
        other GPRs are reserved
      notes:
        - if you specify edi other than 0, then value returned in eax remains
          in edi too (of course)
        - If edi contains 0, CreateBitmap will allocate header in same block
          of memory with pixel array and set TG2D_BITMAP_INTERNAL_ONECHUNK
          flag in "flags" member. If header is specified in edi only pixel
          array is allocated.
        - If TG2D_BITMAP_CLIP flag is specified in eax, then clip rectangle is
          set to entire bitmap (clipx = 0, clipy = 0, clipxsz = xsz = ebx,
          clipysz = ysz = ecx)
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        TG2D_ERROR_OUTOFRANGE (value 4)
          ebx or ecx above 7FFFFFFFh, some position wouldnt be addressable.
          You can't have such big bitmap, but probably you have bug in your
          code.
        TG2D_ERROR_OVERFLOW (value 5)
          size of pixel array too big: xsz*ysz*bytes_per_pixel >= 2^32, again
          like previous one.
        TG2D_ERROR_INVALIDARGS (value 6)
          non-user flags specified in eax. Call was ignored and no bitmap was
          created.
        + errors returned by os.memalloc

    3.2.2 - FreeBitmap
    ==================
      args:
        edi (bitmap*)
          pointer to bitmap to free
      returns:
        eax = -1 on errors, undefined otherwise
        other GPRs are reserved
      notes:
        - if bitmap has TG2D_BITMAP_INTERNAL_ONECHUNK flag set, then header is
          freed too, otherwise all header members are zeroed. (see
          CreateBitmap for more info on this)
        - you cannot free screen bitmap, if you try so TG2D_ERROR_INVALIDARGS
          error is returned.
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        TG2D_ERROR_UNDEFINEDBITMAP (value 9)
          bitmap you entered was undefined ("bmp" member is 0). You are
          freeing bitmap twice or you are trying to free uncreated bitmap. You
          can ignore this error.
        TG2D_ERROR_INVALIDARGS (value 6)
          you are trying to free screen bitmap. You can ignore this error.
        + errors returned by os.memfree

  
  3.3 - Screen
  ============
    Screen is described by screen bitmap. You receive screen bitmap pointer
    from AccesOriginalMode or SetDisplayMode.

    3.3.1 - AccessOriginalMode
    ==========================
      This call gives you access to screen in without changing display mode.
      It can be only used to get access to original mode (in which display was
      when Init was called). If display isn't in original mode (SetDisplayMode
      was called, without restoring with ResetDisplayMode), then
      ResetDisplayMode will be called automaticaly
      
      args: none
      returns:
        eax = -1 on error, 0 if access not supported, pointer to "tg2d.screen"
          otherwise
      notes:
        - if you use this proc to restore original mode, then also check
          ResetDisplayMode's description
        - on some platforms returned screen bitmap structure has "bmp" member
          set to 0 and must be locked before accessing. This should be
          detected by checking TG2D_SCREEN_MUSTBELOCKED flag in
          "tg2d.screenflags".
        - Xsz of returned screen bitmap can be higher than current
          resolution's one, see screen bitmap description for more
          informations on this.
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        TG2D_ERROR_ALREADYDONE (value 10)
          You already called AccessOriginalMode. You can ignore this error.
        + errors returned by os.AccessOriginalMode
        + errors returned by ResetVideoMode if proc wasn't called in original
          display mode
        
    3.3.2 - SetDisplayMode
    ======================
      Sets another display mode (resolution and bit depth)

      args:
        ebx = X resolution of mode to set
        ecx = Y resolution of mode to set
        edx = bytes per pixel of mode to set. (BYTES, not bits!)
      returns:
        eax = -1 on error, otherwise it is pointer to "tg2d.screen"
      notes:
        - Xsz of returned screen bitmap can be higher than one specified in
          ebx, see screen bitmap description for more informations on this.
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        + errors returned by os.SetDisplayMode
    
    3.3.3 - ResetDisplayMode
    ========================
      Returns display to original display mode (the one it was in when Init
      was called). Doesn't give you access to it, it can be done with
      AccessOriginalMode.

      args: none
      returns:
        eax = -1 on error
      notes:
        - called automaticaly by Close if you changed display mode and didnt
          restore it. But better do not rely on this behavior, it would be
          unclear for anyone reading your code.
        - in version for win32 ddraw it returns to state when first
          SetDsiplayMode was called (instead of Init), but this shouldn't
          matter very much.
        - Note this sets original display mode, but doesn't get access to it.
          This can be done by AccessOriginalMode
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        TG2D_ERROR_ALREADYDONE (value 10)
          You are in original display mode already, this call is obsolete. You
          can ignore this error.
        + errors returned by os.ResetDisplayMode

    3.3.4 - Lock
    ============
      On some platforms screen bitmap must be "locked" before you can use it.
      When you use screen bitmap in tg2d routine then tg2d locks it for you if
      it is needed, but in some cases you want to lock it yourself (like when
      you want to modify it with non-tg2d routine)
      
      args: none
      returns:
        tg2d.screen.bmp = valid pointer to displayed pixel array.
        eax = -1 on error, undefined otherwise
        other GPRs are reserved
      notes:
        - On platforms where locking is not required this procedure does
          nothing, otherwise it sets "tg2d.screen.bmp" to valid pointer.
        - Locking takes lot of time, so screen bitmap should be locked only
          once per drawing loop. If you make more consectutive draws onto
          screen bitmap in one loop, you should call Lock before, otherwise
          screen bitmap is locked and unlocked by tg2d for each draw.
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        TG2D_ERROR_NOSCREEN (value 11)
          Screen bitmap is not accessible now. You didn't get access to screen
          with AccessOriginalMode or SetDisplayMode. Nothing is locked,
          otherwise you can ignore this error.
        TG2D_ERROR_ALREADYDONE (value 10)
          Screen bitmap is locked already. You can ignore this error.
        + errors returned by os.Lock


    3.3.5 - Unlock
    ==============
      Unlocks locked bitmap.

      args: none
      returns:
        tg2d.screen.bmp = 0 on platforms on which locking is required.
        eax = -1 on error, undefined otherwise
        other GPRs are reserved
      notes:
        - you should try to spend as few time as possible between Lock and
          Unlock, because purpose of locking is to suspend other processes to
          make sure no one else will change screen. So while screen bitmap is
          locked multitasking is disabled.
        - screen bitmap is unlocked automaticaly when Close is called when it
          is locked
        - if locking is not required, this procedure just returns (before
          checking for any errors except TG2D_ERROR_NOTINITIALIZED).
      errors:
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
        TG2D_ERROR_NOSCREEN (value 11)
          Screen bitmap is not accessible now. You didn't get access to screen
          with AccessOriginalMode or SetDisplayMode. Nothing is unlocked,
          otherwise you can ignore this error.
        TG2D_ERROR_ALREADYDONE (value 10)
          Screen bitmap is unlocked already
        + errors returned by os.Unlock

    3.3.6 - Retrace
    ===============
      Gets vertical retrace status. For smooth animation you should write
      screen only during vertical retrace

      args: none
      returns:
        eax = -1 on error, 0 when retrace is not in progress, 1 during retrace
        other GPRs are reserved
      errors: 
        TG2D_ERROR_NOTINITIALIZED (value 1)
          Init wasnt called
         + errors returned by os.Retrace

4 - Error handling
==================
  TODO

vim: tw=78 expandtab
