MGK Library Manual

Introduction

Graphics Library Structure

mgk
mgi
mhc
mif | mrn
mis
mso | mvm | nusys

- mvm
  handles vectors and matrices.

- mso
  contains all of the share portions, such as memory allocation, etc.

- mis
  handles input from ROM.

- mif
  loads the IFF files.

- mrn
  produces gfx from objects which have no hierarchy.

- mhc
  performs hierarchy evaluation and produces objects which can be rendered by mrn.

- mgi
  provides the means for initializing the application and accessing the hierarchical structure.

- mgk
  is a utility library for easily constructing applications.

Objects in the mgk Library

- MgkApp Performs application management.
  Primary functions and macros

- MgkAppInit Initializes the application.

- MgkAppInitGroups Initializes MrnGroup. MrnGroup plays an essential role in rendering, but it will not be explained here as it is a bit complicated.

- _mgkAppBeginFrame Declares the beginning of a frame. Create Gfx during the period from when _mgkAppBeginFrame is called until _mgkAppEndFrame is called.
  In addition, the screen mode must not be changed (mrnScreenSetMode) during this period.

- _mgkAppEndFrame Declares the end of a frame.

- mgkAppEvalAll Evaluates a hierarchy.

- mgkAppDraw Creates Gfx and returns a pointer to after the last Gfx as a return value.

- mgkObj Performs object management.

  Primary functions and macros

- mgkObjLoad Loads NVF to an object.

- mgkObjCreateCamera Creates a camera object. A camera object is an object which contains only a camera.

- mgkObjMove Performs parallel movement of the object.

- mgkObjRotate Rotates the object.

- mgkObjLookAt Makes it so that the negative direction of the Z axis of the object faces a specified coordinate.

- mgkObjScale Imparts a scale to the object.

- mgkObjSetAnim Selects object animation.

- mgkObjPlayAnim Starts playback of object animation.

Usage Examples

mainproc should be executed as follows.

1. Initialize the default allocator.

   Since the default allocator is used when allocating memory, it must be initialized first before anything else.

           static MsoHeapAllocator     heap_allocator;
           void                        *heap_ptr;

           heap_ptr = _codeSegmentEnd;
           msoHeapAllocatorInit( &heap_allocator,
                                 heap_ptr, 0x80380000 - ( u32 )heap_ptr );
           msoSetDefaultAllocator( _msoUpCast( MsoAllocator, &heap_allocator ) );

   The heap area is managed by MsoHeapAllocator.

   MsoHeapAllocator is initialized by msoHeamAllocatorInit and set in the default allocator by msoSetDefaultAllocator.

   In the above example, the memory area from immediately after codeSegment to 0x80380000 is reserved as the heap area.

2. Initialize the application.

           #define     MAX_OBJS        (4)

           MgkObj      gObjArray[ MAX_OBJS ];

           mgkAppInit( 2, 32768, 65536, 256, 16384, MAX_OBJS, gObjArray, NULL );
           mgkAppInitGroups( );

   The application is initialized by mgkAppInit.

   The subsequent mgkAppInitGroups initializes MrnGroup.

   Initialization of MrnGroup has historically been rather complicated, but this is the simplest initialization method.

   In this example, the following settings are made.

   - Double buffer mode
   - Gfx length = 32768 per frame
   - Frame resource size = 65536 bytes
   - Instance queue size = 256
   - Conversion buffer size = 16384 bytes
   - Maximum number of objects = MAX_OBJS
   - Object array = gObjArray

3. Load the object.

           mgkObjLoad( &gObjArray[ 0 ], ( u32 )_stageSegmentRomStart,
                                        ( u32 )_stageSegmentRomEnd );
           mgkObjLoad( &gObjArray[ 1 ], ( u32 )_animalSegmentRomStart,
                                        ( u32 )_animalSegmentRomEnd );

   Use mgkObjLoad to load the NVF to the object.

   In the above example, the NVF in _stageSegment is loaded to gObjArray[0], and the NVF in

   _animalSegment is loaded to gObjArray[1].

4. Set the camera.

           mgkObjCreateCamera( &gObjArray[ 2 ], 45.0f, 1.333333333f, 5.0f, 2000.0 );

   The camera itself takes up one object.

   mgkObjCreateCamera turns an object into a camera object.

   Camera control is possible by using mgjObjLookAt, etc. on a camera object.

   The following settings are made in this example.

   - Field of view (Y) = 45
   - Aspect ratio = 1.3333333333
   - Clip near = 5
   - Clip far = 2000

5. Main loop

   The method for independently constructing the main loop is introduced here.

           while ( 1 )
           {
               ++gMgiApp.frame_count;
               nuContDataGetExAll( gMgiApp.cont_data );

               _mgkAppBeginFrame( );

               /* Object movement */
               mgkObjMove( &gObjArray[ 1 ], x, y, z );

               /* Face camera in direction of object */
               mgkObjLookAt( &gObjArray[ 2 ],
                             0.0f, 0.0f, 1000.0f,      /* Camera coordinates */
                             x, y, z,                  /* POV coordinates */
                             0.0f, 1.0f, 0.0f );       /* Upward vector */

               mgkAppEvalAll( );
               mgkAppDraw( );
               _mgkAppEndFrame( );
           }

   The main loop must be processed in the following order.

   1. Increment gMuiApp.frame_count.

   2. Read the controller status.

   3. Declare the start of the frame with _mgkAppBeginFrame.

   4. Perform various processing, such as object movement, etc.

   5. Perform hierarchy evaluation with mgkAppEvalAll.

   6. Create gfx with mgkAppDraw.

   7. Declare the end of the frame with _mgkAppEndFrame.

   There are no retrace stand-by's anywhere in this code, but since _mgkAppEndFrame is called in synchronization with the scheduler, processing proceeds as a whole in 1/60 units (as long as a frame is not dropped).