prj/tech/libsrc/compapis/gshelapi.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // $Source: x:/prj/tech/libsrc/compapis/RCS/gshelapi.h $
   3 // $Author: TOML $
   4 // $Date: 1997/09/10 13:57:12 $
   5 // $Revision: 1.33 $
   6 //
   7 // Interfaces for use with the Looking Glass Generic Game Shell.  Game shell
   8 // is responsible for platform dependent synchronization.
   9 //
  10
  11 #ifndef __GSHELAPI_H
  12 #define __GSHELAPI_H
  13
  14 #if defined(__SC__) || defined(__RCC__)
  15 #pragma once
  16 #endif
  17
  18 ///////////////////////////////////////
  19
  20 // Expected includes:
  21 //  "lg.h"
  22 //  "comtools.h"
  23
  24 #include <gshlguid.h>
  25 #include <pumpenum.h>
  26
  27 ///////////////////////////////////////////////////////////////////////////////
  28 //
  29 // Forward Declarations
  30 //
  31 typedef struct grs_bitmap grs_bitmap;
  32 typedef grs_bitmap        sGrBitmap;
  33 typedef struct Point      Point;
  34
  35 F_DECLARE_INTERFACE(IGameShell);
  36 F_DECLARE_INTERFACE(IGameShellAdviseSink);
  37
  38 ///////////////////////////////////////////////////////////////////////////////
  39 //
  40 // Game shell API
  41 //
  42
  43 //
  44 // Create a game shell and add it to the global app-object
  45 //
  46 #define GameShellCreate(flags) \
  47 { \
  48     IUnknown * pAppUnknown = AppGetObj(IUnknown); \
  49     _GameShellCreate(IID_TO_REFIID(IID_IGameShell), NULL, pAppUnknown, flags, 0); \
  50     COMRelease(pAppUnknown); \
  51 }
  52
  53 #define GameShellCreate2(flags, msecBlockSignal) \
  54 { \
  55     IUnknown * pAppUnknown = AppGetObj(IUnknown); \
  56     _GameShellCreate(IID_TO_REFIID(IID_IGameShell), NULL, pAppUnknown, flags, msecBlockSignal); \
  57     COMRelease(pAppUnknown); \
  58 }
  59 //
  60 // Creates a game shell, aggregating it with specfied pOuter,
  61 // use IAggregate protocol if ppGameShell is NULL
  62 //
  63 EXTERN tResult LGAPI _GameShellCreate(REFIID, IGameShell ** ppGameShell, IUnknown * pOuter, int fFlags, int msecBlockSignal);
  64
  65 ///////////////////////////////////////
  66
  67 enum eGameShellCreateFlags
  68 {
  69     //
  70     // Automatically lock display device within Begin/EndFrame() pair
  71     //
  72     kLockFrame = 0x01,
  73
  74     //
  75     // Automatically flip display device on EndFrame(), if flippable
  76     //
  77     kFlipOnEndFrame = 0x02,
  78
  79     //
  80     // Call exit() if OS-specific quit event is detected
  81     //
  82     kExitOnQuitEvent = 0x04,
  83
  84     //
  85     // Automatically capture mouse while button is down
  86     //
  87     kCaptureMouseWhileDown = 0x08,
  88
  89     //
  90     // Show cursor
  91     //
  92     kShowNativeCursor = 0x10,
  93
  94     //
  95     // Attempt to run the game shell in multi-threaded mode
  96     //
  97     kMultithreadedShell = 0x20,
  98
  99     //
 100     // Automatically flush display device on EndFrame()
 101     //
 102     kFlushOnEndFrame = 0x40,
 103
 104     //
 105     // Create default
 106     //
 107     kGameShellDefault = (kLockFrame + kFlipOnEndFrame + kExitOnQuitEvent + kCaptureMouseWhileDown + kFlushOnEndFrame)
 108 };
 109
 110 ///////////////////////////////////////////////////////////////////////////////
 111
 112 typedef enum eGSCursorEvent
 113 {
 114     kGSShowCursor,
 115     kGSHideCursor
 116 } eGSCursorEvent;
 117
 118 typedef void (LGAPI * tGSCursorCallbackFunc)(eGSCursorEvent);
 119
 120 ///////////////////////////////////////////////////////////////////////////////
 121 //
 122 // INTERFACE: IGameShell
 123 //
 124 //
 125
 126 #undef  INTERFACE
 127 #define INTERFACE IGameShell
 128
 129 DECLARE_INTERFACE_(IGameShell, IUnknown)
 130 {
 131     //
 132     // IUnknown methods
 133     //
 134     DECLARE_UNKNOWN_PURE();
 135
 136     //
 137     // Pump-input and lock display surfaces (if specified when created)
 138     //
 139     STDMETHOD_(void, BeginFrame)(THIS) PURE;
 140
 141     //
 142     // Release locks, ensure screen is up-to-date
 143     //
 144     STDMETHOD_(void, EndFrame)(THIS) PURE;
 145
 146     //
 147     // Make sure the game is the user focus
 148     //
 149     STDMETHOD (BringToFront)(THIS) PURE;
 150
 151     //
 152     // Obsolete functon
 153     // @TBD (toml 08-03-97): next time a non-backtouch game shell change goes in, remove this
 154     //
 155     STDMETHOD (Obsolete1)(THIS) PURE;
 156
 157     //
 158     // Process pending events (on event-driven OSs)
 159     //
 160     // This is done automatically in BeginFrame()
 161     //
 162     // This will break all locks, if there are any, then re-lock.  Messages
 163     // will be passed into the event aggregation event handler, if any.
 164     //
 165     // Sprinkle this around if things seem choppy, but not too many places,
 166     // as it can be relatively expensive
 167     //
 168     STDMETHOD_(void, PumpEvents)(THIS_ int fPumpFlags /* = kPumpAll */) PURE;
 169
 170     ///////////////////////////////////
 171     //
 172     // Convenience functions that provide a facade for common operations on
 173     // other components without forcing game shell clients to include headers
 174     // with a lot of irrelevant dependencies
 175     //
 176
 177     //
 178     // Try to lock video memory.  Locked pointers will be placed in
 179     // structure provided in SetMode(). Returns lock count.
 180     //
 181     STDMETHOD_(int, DisplayLock)(THIS) PURE;
 182
 183     //
 184     // Release a lock on memory
 185     //
 186     STDMETHOD_(int, DisplayUnlock)(THIS) PURE;
 187
 188     //
 189     // Verify display reflects what is expected.  Useful if not particularly
 190     // frame based & want to ensure screen is up-to-date within/without a
 191     // BeginFrame()/EndFrame() pair. Meaningful in "artificial" modes, no-op
 192     // otherwise.
 193     //
 194     STDMETHOD_(void, DisplayFlush)(THIS) PURE;
 195
 196     //
 197     // Get the present tick count, in msec since initialization or timer restart
 198     //
 199     STDMETHOD_(unsigned long, GetTimerTick)(THIS) PURE;
 200
 201     //
 202     // Reset the timer (by default, starts at zero from initialization)
 203     //
 204     STDMETHOD_(void , SetTimer)(THIS_ unsigned long) PURE;
 205
 206     //
 207     // Show a help topic
 208     //
 209     STDMETHOD_(BOOL, ShowHelp)(THIS_ const char * pszHelpFile, uint command, ulong dwData) PURE;
 210
 211     //
 212     // Show/Hide the OS cursor.
 213     //
 214     STDMETHOD_(BOOL, SetOSCursor)(THIS_ sGrBitmap * pCursorBitmap, const Point * pHotSpot) PURE;
 215     STDMETHOD_(BOOL, ShowOSCursor)(THIS_ BOOL) PURE;
 216     STDMETHOD_(void, SetCursorCallback)(THIS_ tGSCursorCallbackFunc) PURE;
 217
 218     //
 219     // Execute a command line
 220     //
 221     STDMETHOD_(BOOL, Exec)(THIS_ const char * pszCommandLine ) PURE;
 222
 223     //
 224     // Set flags.  Some flags may be unaffected (e.g., multithreaded)
 225     //
 226     STDMETHOD_(BOOL, SetFlags)(THIS_ int fFlags ) PURE;
 227
 228     //
 229     // Get flags
 230     //
 231     STDMETHOD_(BOOL, GetFlags)(THIS_ int * pfFlags ) PURE;
 232 };
 233
 234 #define IGameShell_QueryInterface(p, a, b)  COMQueryInterface(p, a, b)
 235 #define IGameShell_AddRef(p)                COMAddRef(p)
 236 #define IGameShell_Release(p)               COMRelease(p)
 237 #define IGameShell_BeginFrame(p)            COMCall0(p, BeginFrame)
 238 #define IGameShell_EndFrame(p)              COMCall0(p, EndFrame)
 239 #define IGameShell_PumpEvents(p, a)         COMCall1(p, PumpEvents, a)
 240 #define IGameShell_DisplayLock(p)           COMCall0(p, DisplayLock)
 241 #define IGameShell_DisplayUnlock(p)         COMCall0(p, DisplayUnlock)
 242 #define IGameShell_DisplayFlush(p)          COMCall0(p, DisplayFlush)
 243 #define IGameShell_SetTimer(p, a)           COMCall1(p, SetTimer, a)
 244 #define IGameShell_GetTimerTick(p)          COMCall0(p, GetTimerTick)
 245 #define IGameShell_ShowHelp(p, a, b, c)     COMCall3(p, ShowHelp, a, b, c)
 246 #define IGameShell_SetOSCursor(p, a, b)     COMCall2(p, SetOSCursor, a, b)
 247 #define IGameShell_ShowOSCursor(p, a)       COMCall1(p, ShowOSCursor, a)
 248 #define IGameShell_SetCursorCallback(p, a)  COMCall1(p, SetCursorCallback, a)
 249 #define IGameShell_Exec(p, a)               COMCall1(p, Exec, a)
 250 #define IGameShell_SetFlags(p, a)           COMCall1(p, SetFlags, a)
 251 #define IGameShell_GetFlags(p, a)           COMCall1(p, GetFlags, a)
 252
 253 ///////////////////////////////////////////////////////////////////////////////
 254
 255 #endif /* !__GSHELAPI_H */