******************************************************************************
* Document type: SGL program library description file
* Readme file name: SGL020A.TXT
* Library name: SGL
* Library prefix: SGL
* Version: 2.0A
* Creator: K.T.
* Created: 2/9/96
* Comments: None
******************************************************************************

1. Version Update Information (1.31->2.00->2.0A updates)

   Ver2.0A updates are denoted as -->Ver2.0A in the header.

1.1 Expanded Functions and Speed Optimization

1) Expanded Sprite Display Functions (See sprite.doc)

   Sprite functions that support independent horizontal/vertical scaling,
   horizontal/vertical sizing, and display of a sprite based on 4 user
   specified vertices were added.

   a) slDispSpriteHV function

      Displays distorted sprites based on vertical and horizontal display
      scaling values. Compared with slDispSprite, negative values specified
      for the scaling value display the character in reverse.

   b) slDispSpriteSZ function

      Displays distorted sprites based on vertical and horizontal display
      scaling values. When a negative value is selected for the size, the
      character is displayed in reverse.

   c) slDispSprite4P function

      Displays a distorted sprite at 4 user-specified vertices.  The four
      points are specified as offset positions relative to the center of the
      window.  A representative Z position for the four points is assigned
      separately.  The 4 points are set clockwise in upper left, upper
      right, lower right, and lower left order.

2) Changes in the Master and Slave CPU Communication Method.

   When the slave CPU is idle, access to the master CPU from the slave has
   been reduced by monitoring the FRT input capture signal instead of
   the master CPU's command pointer through a cache-through memory area.

3) Addition of slFrameClipSize

   slFrameClipSize has been added to enable changes in the clipping region
   for sprites and polygons with the UseClip option enabled.

4) Distorted Sprite Draw Optimization

   When distorted sprites (also includes textures) are displayed, a check is
   performed to see whether vertices exist within a window. The character is
   flipped and vertices are swapped as necessary to reorient vertex 0 within
   the window. The drawing efficiency of distorted sprites that go outside
   the window has been improved by the implementation of this software
   preclipping.

5) Stunner (Virtua Gun) Support

   The library now supports the Stunner.  However, it is also necessary to
   implement code within the application for this support.  See the sample
   code in the DEMOGUN directory for more information.

6) CD Library Upgrades --> Ver2.0A

   The following versions of the libraries are included:

   * CD Communication Interface Library (CDC)           Ver. 1.20
   * File System Library                (GFS)           Ver. 2.10
   * Stream System Library              (STM)           Ver. 2.10

   The libraries are now divided into 2 types:

   LIBCD.A   --> No File System (GFS) debug support.
   LIBCD_D.A --> File System (GFS) debug support.

1.2 Bug Fixes

1) Changing CPU DMA Transfer Channel Used Internally by the Library

   CPU DMA transfers are used in sound-related data transfers within SGL.
   However, the CPU DMA transfer channel used for a scroll screen data
   transfer conflicts with this sound data CPU DMA transfer when a V-blank
   interrupt occurs.  As a result, the CPU DMA channel used for sound data
   transfers has been changed.

   CPU DMA transfer channel 1 is now reserved for system use.  If a CPU DMA
   is required by the application, always use channel 0 or use slDMACopy or
   slDMAXCopy.

2) slSoundRequest Bug Fix

   Due to the differences in Hitachi and GNU SH2 code generation, registers
   were not being preserved in the same manner. This caused commands to be
   issued incorrectly.  This problem has now been corrected.

3) Bitmap Function Fix

   The table order and parameter values for slBitMapNbg0 and slBitMapNbg1
   did not match.  This resulted in bitmap sizes being mistaken for the
   number of bytes. This problem has been corrected.

4) slCharNbg3 2x2 Cell Bug Fix

   slCharNbg3 did not display 2x2 (CHAR_SIZE_2x2) character sizes correctly.
   This has now been fixed.

5) WORKRAM-L Support for PCM Playback Data

   Since SGL uses SCU DMAs to transfer PCM data, PCM data located in
   WORKRAM-L could not be transferred.  This resulted in a bug where PCM
   playback did not occur correctly.  This problem has now been solved.
   However, the 3 following guidelines must be followed when placing data in
   WORKRAM-L:

   a) Playback data must be located from an even address. (The lower 1 bit
      of the address is used as 0.)
      -> Place data from an even address.
  
   b) When playback data is stereo 8 bit, the left channel data must be
      located from an even address.
      -> Adjust the number of samples to be even.
  
   c) A noise glitch occurs when playback data is over 8192 frames and
      overflows the buffer.
       -> Define the data so that 1 byte is duplicated every 8192 frames.
          However, the start of data will begin with a frame offset of 1536
          frames (600H).  Accordingly, the first data that is duplicated is
          at 6656 (1A00H).

6) slPutPolygon Vertex Count 0 Support

   In the polygon display function slPutPolygon, specifying 0 for the number
   of vertices and polygons caused the loop counter to max out and crash the
   application.  A vertex count of 0 is now supported.  However, the
   application must not allow this function to be executed when the polygon
   count is 0.

7) slRotAX Bug

   The math error in the slRotAX function has been corrected. Documentation
   errors regarding this function were also corrected.

1.3 Sample Program Fixes and Additions

1) Backup Memory Sample Program Bug (SBKLIB)

   There was a programming error in the Backup Library sample program.  An
   error was made in retrieving time data from the SMPC.  The fixes have
   been commented in the code.

2) Stunner Sample Program (DEMOGUN)

   A sample program was added to explain how to read data from a Stunner.
   
3) Makefile Update

   An example is given to convert a COFF file to a binary format file.
   OBJCOPY.EXE from the GNU tool set is used for this example.
      
4) Addition of Initialization Processing [Important!] --> Ver2.0A

   To set up a C program execution environment, the following steps must be
   taken:

   * Zero clear all uninitialized data areas (mandatory).
   * Copy initialization data from ROM to RAM (not normally required).
   
   Perform these settings from the application.
   
   An example of this process has been included in SGL's sample code.
   Accordingly, the following changes have been made from previous sample
   programs:

   * A common initialization program has been added to the COMMON directory.
     main is used for the function name.

   * main, a function name in the previous version of the sample program was
     changed to ss_main.  ss_main is called after the initialization
     function completes the initialization process.
     
   * sl.lnk (section declaration file) created with a makefile is supplied
     as a file in the COMMON directory.

   SGL may not function properly if the initialization process shown in the
   sample program is not performed.  Make sure to initialize the system! 

2. Revision History

2.1 Changes from Ver1.3 to Ver1.31

1) Address Error Fix

   An address error that occurred in slInitSound was fixed.

2) DMA_ScuResult Fix

   Bugs in DMA_ScuResult (the function has the same specifications as that
   found in SBL) was fixed.

2.2 Changes from Ver1.21 to Ver1.3

1) User Defined Work Areas (see memory.doc)

   The system work area now supports user-defined memory allocation. See
   memory.doc for details.

2) VDP1 Draw End Wait (Dynamic Frame Change) Mode Support (see init.doc)

   A dynamic frame change mode was added to advance the main program
   sequence upon completion of VDP1 draw processing. First, a negative value
   is set to the frame counter when slInitSystem is executed. The MSB of
   (Sint8)Resolution then becomes 1 and the VDP1 draw end check is added.
   However, note that an extra draw step takes place in this mode since a
   sprite the size of the entire screen is drawn to clear the frame buffer.
   A function was added to support this mode:

   * slDynamicFrame: Switches between fixed-period and VDP1 draw end wait
                     (dynamic) frame change.

3) Window Function Feature Expansion (see sprite.doc)

   Support was added to switch the sprite (polygon) display window on the
   fly. Before this feature, a switch to the foreground window occurred
   whenever slWindow was executed. In comparison, the display window can be
   selected with slCurWindow. The frequency of window settings is reduced
   since window states are also preserved.

   Example:

     slCurWindow(winFar);
     slWindow(--- for Far side Window ---);
     slCurWindow(winNear);
     slWindow(--- for Near side Window ---);

     ...

     slCurWindow(winFar);
     slPutPolygon(PD_XX);        /* Display to game screen */
     slCurWindow(winNear);
     slPutPolygon(PD_xx);        /* Display to map */

     slCurWindow(...);

   The display window is winFar after the slSynch function is executed.
   Display processing occurs in the same window until a window switching
   function (slWindow or slCurWindow that takes place after a display
   function such as slPutPolygon) is executed.

   Note:

   Only the following function parameters are switched by slCurWindow:

   * slWindow, slZdspLevel, slPerspective

     Note that the environment matrix and light-source vector are not reset.
     The current window number (winFar, winNear) is returned when
     slSprWinNum is executed.

4) PAL Support

   A 256 line screen mode was added to support PAL.

     TV_320x256, TV_352x256, TV_640x256, TV_704x256
     TV_320x512, TV_352x512, TV_640x512, TV_704x512

5) Addition of a Video Mode Change Function (see init.doc)

   The slSetTVMode function was added for changing the video mode.  However,
   note that video modes that change the system clock speed will return an
   error.

6) Addition of an External Signal Enable Control Register Setup Function 
   (see scroll.doc)

   The slExtSignal function was added to enable the support of external
   signal input such as MPEG video.

7) Addition of Scroll Screen Scaling Functions (see scroll.doc)

   The following functions were added for setting the scale amount for
   scroll screens:

   slScrScaleNbg0, slScrScaleNbg1, and slScrScaleR

8) Display Polygon Models Using Object Structures (see sprite.doc)

   Polygon models can be displayed using positions, rotation angles, and
   scale amounts set in OBJECT structures. The process is similar to that
   performed for the following function:

      void slPutObject(OBJECT *obptr)
      {
          slTranslate(obptr->pos[X], obptr->pos[Y], obptr->pos[Z]);
          slRotZ(obptr->ang[Z]);
          slRotY(obptr->ang[Y]);
          slRotX(obptr->ang[X]);
          if(obptr->pat != NULL) {
              slPutPolygon(obptr->pat);
          }
      }

   For example, the following function can be created to display object
   groups with parent/child structures:

      void PutAll(OBJECT *obptr)
      {
          slPushMatrix();
          {
              slPutObject(obptr);
              if(obptr->child != NULL){
                  PutAll(obptr);
              }
          }
          slPopMatrix();
          if(obptr->sibling != NULL) {
              PutAll();
          }
      }

9) Addition of Debug Functions (see packs.doc)

   The following functions for displaying debug text were added:
     slCurScrn    : Selects scroll screen for text display.
     slLocateNbg  : Calculates the display address on the specified scroll
                    screen.
     slLocatePage : Calculates the display address on the specified page
                    number.

10) Addition of slPutPolygonS Function (see sprite.doc)

    A function was added to perform polygon display processing entirely on
    the slave CPU.
    
    Although slPutPolygon passes on a portion of display processing
    calculations to the master depending on the slave's processing state,
    slPutPolygonS forces all display processing on the slave. This function
    should be used to reduce the slave's idle time between the execution of
    slSynch and the first processing request made to the slave.  

    For example, slPutPolygonS is useful when all display data is prepared
    in advance during a loop before its execution. After slSynch is
    executed, all polygon display requests are issued as a batch at the
    beginning of the main loop.

11) Addition of 256 Color Bitmap Graphics Functions (see bitmap.doc)

    Bitmaps are used to treat a VDP2 scroll screen as one display screen.
    This library only supports the 256 color palette mode. After the regular
    initialization process is completed, slInitBitMap is used to initialize
    settings for these bitmap functions. See bitmap.doc for the function
    specifications.

12) Addition of Matrix Calculation Functions (see math.doc)

    The following functions were added for matrix calculations:

    * slIncMatrixPtr

      Increments the matrix stack pointer. Compared with slPushMatrix,
      the matrix is not copied.

    * slDecMatrixPtr

      Decrements the matrix stack pointer. Same as slPopMatrix.

    * slRegistMatrix

      Copies the current matrix to a temporary register.

    * slRegistTranslate

      Parallel shifts (translates) a matrix in the temporary register and
      sets it to the current matrix.  The temporary register is not
      modified.  This function can be used to minimize the overhead that
      occurs when slPushMatrix and slPopMatrix are used extensively.
      
    * slUnitAngle

      Initializes only the rotational portion of the current matrix.

    * slUnitTranslate

      Initializes only the translated portion of the current matrix.

    * slGetTranslate

      Gets the translated portion of the current matrix and copies it to a
      selected buffer. The current matrix is not modified.

    * slCopyMatrix

      Copies the penultimate matrix to the current matrix.

    * slLoadTranslate

      Changes the translated portion of the current matrix to the specified
      value.  The rotational portion is not modified.

    * slCheckOnScreen0

      This function executes the slCheckOnScreen with the coordinates
      (0,0,0). 

13) Addition of Constant and Conversion Macros

    The following constants and conversion macros were added:

    * M_PI       Pi
    * RADtoANG   Converts radian to angle.
    * SLocate    Calculates scroll display position.
    * MSBon      Sprite shade enable bit

2.3 Changes from Ver1.2 to Ver1.21

1) slAtan Boundary Value Bug Fix

   When absolute values of parameters tx and ty were equal, the correct
   angle was not returned.

2) DMA Function Bug

   A bug in the DMA_ScuMemCopy function ported from SBL was fixed.
   
3) Elimination of slSetTrayCheck

   CD-related functions could not execute properly when slSetTrayCheck was
   executed. This function is no longer distributed because of this problem.
   
   As an alternative, get the CD door open status by using the CDCGetHirqReq
   function and create a handler routine in your application.

4) Sample Program DEMO_D Polygon "Drift" Problem

   The polygon had a tendency to move even when no pad input was made in 
   sample program DEMO_D.  This problem was fixed.
   
2.4 Changes from Ver1.1 to Ver1.2

1) CPU Deadlock at Sprite Display

   The master CPU and slave CPU may deadlock when no sprites are displayed.
   This problem has been fixed.

2) CD Filename Length Bug Fix

   A bug existed where a filename could be only 7 characters + "." + 3
   characters in the CD-ROM file system (libcd.a). This bug has been fixed
   so that 8 characters + "." + 3 characters can be used.

2.5 Changes from Ver1.0 to Ver1.1

1) Improvements to Resolution of Trigonometric Functions

   The resolution of trigonometric calculation results were improved 8x by
   increasing data resolution in trig function data tables.

2) Support for Debugger-Induced Program Halts During Peripheral Servicing

   The effects of program halts invoked by the debugger during a peripheral
   interrupt service routine were eliminated.

3) Improvement in Display of Rectangular Sprites

   When the scaling amount for a rectangular sprite display is set at 1.0,
   due the actual sprite was displayed 1 pixel larger vertically and
   horizontally than the selected size due to hardware limitations. This
   problem has been fixed.

4) Frame Change Timing Change

   In version 1.0, unfinished sprite draws were carried over to the next
   frame whenever sprite data calculations were incomplete when frame change
   occurred.  This timing has been changed from version 1.1 so that any
   undisplayed sprites within a frame are discarded and not carried over to
   the next frame.
