home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga 5 / MA_Cover_5.iso / ppc / mesa / src / s3dtk.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-01-31  |  24.5 KB  |  705 lines
  1. /************************************************************************************\
  2.   S3D ToolKit library.
  3.  
  4.   Copyright S3 Inc, 1995 - 1997.
  5.  
  6.   History
  7.   -------
  8.   ??-??-?? AL Initial library by Alex Lyashevsky
  9.   97-09-08 MH cleanup
  10. \************************************************************************************/
  11.  
  12. #ifndef __S3DTK_H
  13. #define __S3DTK_H
  14.  
  15. /*
  16.   S3D ToolKit library is aimed to ease programming the S3 graphical
  17.   controller advanced 3D/2D capabilities. It is conceptually a HAL
  18.   of the S3D engine with several utility functions.
  19.  
  20.   Environment and OS requirement:
  21.  
  22.   1. DOS + Rational System Extender.
  23.   2. WIN95 + S3KRNL32.DLL + S3KERNEL.VXD.
  24.  
  25.   The library consists of four groups of functions :
  26.  
  27.   1. Set/GetState functions.
  28.   2. 3D primitive functions.
  29.   3. 2D primitive functions.
  30.   4. Initialization and service functions.
  31.  
  32.   Outline for multi-threading Apps.
  33.  
  34.   1. Renderers created in different processes and in different thread of
  35.   the same process could rely on the contention resolving scheme built in
  36.   the ToolKit library. There is no need for explicit call to S3DK_EnterCritical
  37.   if an user calls any ToolKit rendering functions (2D or 3D).
  38.  
  39.   2. If however user will decide to use S3D_EnterCtritical/ ReleaseCritical
  40.   (it might be if he/she uses the library by single primitive basis but needs
  41.   to prevent another app to use S3 2D/3D HW per primitives' packet basis)
  42.   there is no restriction to use them.
  43.   An user could call EnterCritical several times without any harm - only the
  44.   first call will be taken into account. Similarly he/she can call
  45.   ReleaseCritical pretty flexible. If there was a previous EnterCritical call
  46.   from the same thread the critical section will be freed for entering by any
  47.   other threads. If there was not at least one EnterCritical from the thread
  48.   there will not be any action.
  49. */
  50.  
  51. #ifdef __cplusplus
  52. extern "C" {
  53. #endif
  54.  
  55. /************************************************************************************\
  56.    Definitions and macros
  57. \************************************************************************************/
  58.  
  59. #ifdef  __DOS__
  60.   // Set structure packing on long word boundaries
  61.   #define DllExport     ULONG
  62. #else
  63.   #define DllExport     __declspec(dllexport) ULONG _cdecl
  64. #endif
  65.  
  66. #define S3DTKVALUE  float
  67. #define S3DTK_TRUE  1
  68. #define S3DTK_FALSE 0
  69.  
  70. #define S3DTK_ERR    0
  71. #define S3DTK_OK    1
  72.  
  73. #define S3DTK_ON    1
  74. #define S3DTK_OFF    0
  75.  
  76. /*** Set/GetState functions' KEY parameters
  77. ***/
  78.  
  79. typedef enum {
  80.  
  81.   /*** SYSTEM INFORMATION 
  82.   ***/
  83.  
  84.   /* Returns version number in the lowest 2 bytes (Get) */
  85.   S3DTK_VERSION,
  86.  
  87.   /* VIDEO/MEMORY CONTROL AND INFORMATION (DOS ONLY) */
  88.  
  89.   /* Sets possible SVGA video mode (see the list below) (Set)
  90.      Returns current video mode (Get) */
  91.   S3DTK_VIDEOMODE,
  92.   /* Returns linear address of the video memory (Get) */
  93.   S3DTK_VIDEOMEMORYADDRESS,
  94.   /* Returns size of the video memory (Get) */
  95.   S3DTK_VIDEOMEMORYSIZE,
  96.  
  97.   /*** BUFFERIZATION
  98.   ***/
  99.  
  100.   /* Sets current rendering surface using a pointer to the S3DTK_SURFACE
  101.   // structure (see STRUCTURES section) as a second parameter (Set).
  102.   // Returns information of the current rendering surface using
  103.   // the second parameters as pointer to memory where the content
  104.   // of the S3DTK_SURFACE structure will be copied (Get) */
  105.   S3DTK_DRAWSURFACE,
  106.   /* Sets current visible surface using pointer on the S3DTK_SURFACE
  107.   // structure (see STRUCTURES section) as a second parameter (Set) (DOS ONLY).
  108.   // Returns information of the current visible surface using
  109.   // the second parameters as a pointer to memory where the content
  110.   // of the S3DTK_SURFACE structure will be copied (Get) (DOS ONLY) */
  111.   S3DTK_DISPLAYSURFACE,
  112.   /* Returns 1 if Vsync interrupt status pending (display has been
  113.   // fully refreshed), otherwise returns 0. (Get). 
  114.   // This call can be used to prevent current the visible surface 
  115.   // from being overdrawn by the next one or skipping previous frame */
  116.   S3DTK_DISPLAYADDRESSUPDATED,
  117.   /* Returns S3DTK_TRUE if S3 graphical engine idle. The call gives the 
  118.   // correct time point for switching back anf fron buffer */
  119.   S3DTK_GRAPHICS_ENGINE_IDLE,
  120.   /* Turns OFF and ON DMA in DMA data transfer mode */
  121.   S3DTK_DMA_OFF,
  122.   S3DTK_DMA_ON,
  123.  
  124.   /*** RENDERING TYPE
  125.   ***/
  126.  
  127.   /* Sets/returns current rendering type (see list below) (Set/Get) */
  128.   S3DTK_RENDERINGTYPE,
  129.  
  130.   /*** Z BUFFER CONTROL
  131.   ***/
  132.  
  133.   /* Sets/Returns Z-buffer offset in video memory (Set/Get) */
  134.   S3DTK_ZBUFFERSURFACE,
  135.   /* Sets/returns Z-buffer compare mode (see the list below) (Set/Get) */
  136.   S3DTK_ZBUFFERCOMPAREMODE,
  137.   /* Sets Z-buffering off or on with value eq S3DTK_OFF or S3DTK_ON 
  138.   // respectively (Set). Note: ZBUFFERENABLE should be called after 
  139.   // setting rendering buffer; otherwise the call will return an error. */
  140.   S3DTK_ZBUFFERENABLE,
  141.   /* Enables or disables Z-buffer updating. 
  142.   // By default it is enabled but might be disabled for transparency */
  143.   S3DTK_ZBUFFERUPDATEENABLE,
  144.  
  145.   /*** TEXTURE CONTROL
  146.   ***/
  147.  
  148.   /* Sets current texture using a pointer to the S3DTK_SURFACE
  149.   // structure (see STRUCTURES section) as a second parameter (Set).
  150.   // Returns information of the current texture using the second parameter
  151.   // as pointer to memory where the content of the S3DTK_SURFACE structure 
  152.   // will be copied to (Get) */
  153.   S3DTK_TEXTUREACTIVE,
  154.   /* Sets/returns current texture filtering mode (see the list below) (Set/Get) */
  155.   S3DTK_TEXFILTERINGMODE,
  156.   /* Sets/returns current texture blending mode (see the list below) (Set/Get) */
  157.   S3DTK_TEXBLENDINGMODE,
  158.   /* Sets/returns the maximum number of mipmap levels for textures (Set/Get) */
  159.   S3DTK_TEXMAXMIPMAPLEVEL,
  160.  
  161.   /*** ALPHABLENDING
  162.   ***/
  163.  
  164.   /* Sets/returns current way of using ALPHA channel (see the list below) (Set/Get) */
  165.   S3DTK_ALPHABLENDING,
  166.   
  167.   /*** FOG
  168.   ***/
  169.  
  170.   /* Sets current color for fogging in RGBX888 format and turns fogging on. If value 
  171.   // is eq S3DTK_FOGOFF fogging will be tuned off (Set)
  172.   // Returns current fog color or S3DTK_FOGOFF if fogging is off (Get) */
  173.   S3DTK_FOGCOLOR,
  174.   /* If S3DTK_ON is set the Toolkit won't compute D level but will use D specified
  175.   // from application instead, otherwise (S3DTK_OFF - default) D will be computed 
  176.   // within the Toolkit. */
  177.   S3DTK_D_LEVEL_SUPPLIED,
  178.  
  179.   /*** MISC STUFF
  180.   ***/
  181.  
  182.   /* Set/Get clipping sub-rect area inside a current rendering surface */
  183.   S3DTK_CLIPPING_AREA,
  184.  
  185.   /* Flip and wait until done (default is S3DTK_TRUE) - DOS only */
  186.   S3DTK_FLIP_WAIT
  187.  
  188. } S3DTK_STATEKEY;
  189.  
  190. /*** SUPPORTED VIDEO MODES 
  191. ***/
  192. #define S3DTK_MODE320x200x8       0x13
  193. #define S3DTK_MODE320x200x15      0x10D
  194. #define S3DTK_MODE512x384x8       0x215
  195. #define S3DTK_MODE512x384x15      0x216
  196. #define S3DTK_MODE640x400x8       0x100
  197. #define S3DTK_MODE640x480x8       0x101
  198. #define S3DTK_MODE640x480x15      0x110
  199. #define S3DTK_MODE640x480x24      0x112
  200. #define S3DTK_MODE800x600x8       0x103
  201. #define S3DTK_MODE800x600x15      0x113
  202. #define S3DTK_MODE800x600x24      0x115
  203. #define S3DTK_MODE1024x768x8      0x105
  204. #define S3DTK_MODE1024x768x15     0x116
  205. #define S3DTK_MODE1024x768x24     0x118
  206.  
  207. #define S3DTK_MODESET_NO_CLEAR    0x8000    /* OR the mode with this flag to */
  208.                                             /* set mode without clear the    */
  209.                                             /* video memory                  */
  210.  
  211. /*** POSSIBLE RENDERING TYPES 
  212. ***/
  213. #define S3DTK_GOURAUD               0L
  214. #define S3DTK_LITTEXTURE            0x8000000L
  215. #define S3DTK_UNLITTEXTURE          0x10000000L
  216. #define S3DTK_LITTEXTUREPERSPECT    0x28000000L
  217. #define S3DTK_UNLITTEXTUREPERSPECT  0x30000000L
  218.  
  219. /*** Z COMPARE MODES 
  220. ***/
  221. #define S3DTK_ZNEVERPASS            0L
  222. #define S3DTK_ZSRCGTZFB             0x100000L
  223. #define S3DTK_ZSRCEQZFB             0x200000L
  224. #define S3DTK_ZSRCGEZFB             0x300000L
  225. #define S3DTK_ZSRCLSZFB             0x400000L
  226. #define S3DTK_ZSRCNEZFB             0x500000L
  227. #define S3DTK_ZSRCLEZFB             0x600000L
  228. #define S3DTK_ZALWAYSPASS           0x700000L
  229.  
  230. /*** SUPPORTED TEXTURE COLOR FORMATS 
  231. ***/
  232. #define FORMAT_SHIFT  5
  233. #define S3DTK_TEXARGB8888      ( 0 << FORMAT_SHIFT )
  234. #define S3DTK_TEXARGB4444      ( 1L << FORMAT_SHIFT )
  235. #define S3DTK_TEXARGB1555      ( 2L << FORMAT_SHIFT )
  236. #define S3DTK_TEXPALETTIZED8   ( 6L << FORMAT_SHIFT )
  237.  
  238. /*** TEXTURE FILTERING MODE 
  239. ***/
  240. #define FILTER_SHIFT  12
  241. #define S3DTK_TEXM1TPP         ( 0L << FILTER_SHIFT )  /* MIP_NEAREST */
  242. #define S3DTK_TEXM2TPP         ( 1L << FILTER_SHIFT )  /* LINEAR MIP NEAREST */
  243. #define S3DTK_TEXM4TPP         ( 2L << FILTER_SHIFT )  /* MIP LINEAR */
  244. #define S3DTK_TEXM8TPP         ( 3L << FILTER_SHIFT )  /* LINEAR MIP LINEAR */
  245. #define S3DTK_TEX1TPP          ( 4L << FILTER_SHIFT )  /* NEAREST ( NO MIP ) */
  246. #define S3DTK_TEXV2TPP         ( 5L << FILTER_SHIFT )  /* thought to be VIDEO but actually is linear filter */
  247. #define S3DTK_TEX4TPP          ( 6L << FILTER_SHIFT )  /* LINEAR ( NO MIP ) */
  248.  
  249. /*** TEXTURE BLENDING MODE 
  250. ***/
  251. #define BLEND_MODE_SHIFT 15
  252. #define S3DTK_TEXMODULATE         ( 1L << BLEND_MODE_SHIFT )
  253. #define S3DTK_TEXDECAL            ( 2L << BLEND_MODE_SHIFT )
  254.  
  255. /*** ALPHA BLENDING TYPES 
  256. ***/
  257. #define ALPHA_BLEND_CONTROL_SHIFT   18
  258. #define S3DTK_ALPHAOFF               0
  259. #define S3DTK_ALPHATEXTURE           2 << ALPHA_BLEND_CONTROL_SHIFT
  260. #define S3DTK_ALPHASOURCE            3 << ALPHA_BLEND_CONTROL_SHIFT
  261.  
  262. /*** FOG
  263. ***/
  264. #define S3DTK_FOGOFF        0xFFFFFFFF
  265.  
  266. /*** ERROR LIST 
  267. ***/
  268. #define S3DTK_3DCAPNOTSUPPORTED       -1    /* 3D capabilities are not supported */
  269. #define S3DTK_CANTCONVERT             -2    /* cant convert from linear to phys address */
  270. #define S3DTK_INVALIDFORMAT           -3    /* invalid format */
  271. #define S3DTK_NULLPOINTER             -4    /* null pointer */
  272. #define S3DTK_INVALIDRENDETINGTYPE    -5    /* invalid rendering type */
  273. #define S3DTK_INVALIDVALUE            -6    /* invalid value*/
  274. #define S3DTK_UNSUPPORTEDVIDEOMODE    -7    /* unsupported video mode */
  275. #define S3DTK_INVALIDFILTERINGMODE    -8    /* invalid filtering mode */
  276. #define S3DTK_UNSUPPORTEDKEY          -9    /* unsupported key */
  277. #define S3DTK_UNSUPPORTEDMETHOD       -10    /* unsupported method */
  278. #define S3DTK_INVALIDSURFACE          -11    /* surface is not set */
  279. #define S3DTK_NOS3KERNEL              -12    /* can't find S3KERNEL VxD */
  280.  
  281. /************************************************************************************\
  282.    Structures (and acompanying definitions)
  283. \************************************************************************************/
  284.  
  285. /*** S3DTK_LIB_INIT
  286. ***/
  287. typedef struct _S3DTK_LIB_INIT {
  288.  
  289.   ULONG libFlags;                    /* see LIB_INIT Flags below */
  290.   ULONG libVideoBufferLinAddr;        /* DO not use */
  291.   ULONG libMMIOSpaceLinAddr;        /* DO not use */
  292.  
  293. } S3DTK_LIB_INIT, * S3DTK_LPLIB_INIT;
  294.  
  295. /*** LIB_INIT Flags
  296. ***/
  297. #define S3DTK_INITPIO                    0        /* programming device using registers */
  298. #define S3DTK_INITDMA                    1        /* programming device using command DMA */
  299. #define S3DTK_INIT2D_SERIALIZATION_ON    2        /* serialize access to S3D endine */
  300. #define S3DTK_INIT_DMA_SIZE_64K          0x10    /* if bit 0 is set this bit defines the DMA size */
  301.                                                 /* either needed or provided. if 0 - 4K( default ), 1 - 64k */
  302. /* DO not use */
  303. #define S3DTK_INIT_VIDEO_BUFFER_ADDR_PROVIDED 4 /* addrs for video buff and MMI0 space are */
  304.                                                 /* provided by this call */
  305. /* DO not use */
  306. #define S3DTK_INIT_DMA_BUFFER_ADDR_PROVIDED 8    /* address of contigiuos memblock for DMA */
  307.                                                 /* is supplied */
  308.  
  309. /*** S3DTK_RENDERER_INITSTRUCT
  310. ***/
  311. typedef struct {
  312.  
  313.   ULONG initFlags;        /* see RENDERER_INITSTRUCT Flags bits below */
  314.   ULONG initUserID;        /* see RENDERER_INITSTRUCT User ID below */
  315.   ULONG initAppID;        /* see RENDERER_INITSTRUCT App ID below */
  316.  
  317. } S3DTK_RENDERER_INITSTRUCT, * S3DTK_LPRENDERER_INITSTRUCT;
  318.  
  319. /*** RENDERER_INITSTRUCT Flags Bits
  320. ***/
  321. #define S3DTK_GENERIC         0   /* float + do not clip UV + do not clip XY */
  322. #define S3DTK_FORMAT_FLOAT    0
  323. #define S3DTK_FORMAT_FIXED    1L  /* not implemented */
  324. #define S3DTK_VERIFY_UVRANGE  2L  /* is needed only for perspactive texture mapping */
  325. #define S3DTK_VERIFY_XYRANGE  4L  /* is needed if upper layer sw does not consider to clip */
  326.                                   /* along the view port window */
  327.  
  328. /*** RENDERER_INITSTRUCT User ID
  329. ***/
  330. #define S3DTK_USER_GENERIC 0
  331. #define S3DTK_USER_WIN95   1
  332.  
  333. /*** RENDERER_INITSTRUCT App ID
  334. ***/
  335. #define S3DTK_APP_GENERIC 0
  336. #define S3DTK_APP_D3D     1
  337.  
  338. /*** S3DTK_SURFACE
  339. ***/
  340. typedef struct {
  341.  
  342.   ULONG sfOffset;        /* offset either in sytem or video memory */
  343.   ULONG sfWidth;        /* width of surface in pixel */
  344.   ULONG sfHeight;       /* height of surface in pixel */
  345.   ULONG sfFormat;       /* format and location of surface, see SUPPORTED SURFACE */
  346.                         /* FORMATS below */
  347.   ULONG reserved[ 5 ];    /* DO not use */
  348.  
  349. } S3DTK_SURFACE, * S3DTK_LPSURFACE;
  350.  
  351. /*** SUPPORTED SURFACE FORMATS 
  352. ***/
  353. #define S3DTK_VIDEORGB8           0                /* palettized */
  354. #define S3DTK_VIDEORGB15          0x4L            /* 5, 5, 5    */
  355. #define S3DTK_VIDEORGB24          0x8L            /* 8, 8 ,8    */
  356. #define S3DTK_SYSTEM              0x80000000L   /* surface is in system memory*/
  357. #define S3DTK_VIDEO               0x00000000L   /* surface is in video memory */
  358. #define S3DTK_TEXTURE             0x40000000L   /* surface for texture        */
  359. #define S3DTK_Z16                 0x10000000L   /* artificial Z-buffer format */
  360.  
  361. /*** S3DTK_RECTAREA
  362. ***/
  363. typedef struct {
  364.  
  365.   long int left;
  366.   long int top;
  367.   long int right;
  368.   long int bottom;
  369.  
  370. } S3DTK_RECTAREA, * S3DTK_LPRECTAREA;
  371.  
  372. /*** S3DTK_VERTEX_LIT
  373. ***/
  374. typedef struct _s3dtk_vertex_lit
  375. {
  376.  
  377.   S3DTKVALUE  X;
  378.   S3DTKVALUE  Y;
  379.   S3DTKVALUE  Z;
  380.   S3DTKVALUE  W; /* not used */
  381.   BYTE        B;
  382.   BYTE        G;
  383.   BYTE        R;
  384.   BYTE        A;
  385.  
  386. } S3DTK_VERTEX_LIT, * S3DTK_LPVERTEX_LIT;
  387.  
  388. /*** S3DTK_VERTEX_TEX
  389. ***/
  390. typedef struct _s3dtk_vertex_tex {
  391.  
  392.   S3DTKVALUE X;
  393.   S3DTKVALUE Y;
  394.   S3DTKVALUE Z;
  395.   S3DTKVALUE W;
  396.   BYTE       B;
  397.   BYTE       G;
  398.   BYTE       R;
  399.   BYTE       A;
  400.   S3DTKVALUE D;
  401.   S3DTKVALUE U;
  402.   S3DTKVALUE V;
  403.  
  404. } S3DTK_VERTEX_TEX, * S3DTK_LPVERTEX_TEX;
  405.  
  406. /************************************************************************************\
  407.    Function prototypes
  408. \************************************************************************************/
  409.  
  410. /*** Acceptable primitive types for TriangleSet/TriangleSetEx
  411. ***/
  412. #define S3DTK_TRILIST  0
  413. #define S3DTK_TRISTRIP 1
  414. #define S3DTK_TRIFAN   2
  415. #define S3DTK_LINE     3
  416. #define S3DTK_POINT    4
  417.  
  418. /*** S3DTK FUNCTIONS LIST
  419. ***/
  420. typedef struct _s3dtk_function_list *S3DTK_LPFUNCTIONLIST;
  421. typedef struct _s3dtk_function_list
  422. {
  423.  
  424.   /*** 1. Set/GetState functions
  425.   **** -------------------------
  426.   ***/
  427.  
  428.   /* Set 3D engine states */
  429.   ULONG (* S3DTK_SetState)(S3DTK_LPFUNCTIONLIST pFuncStruct,
  430.                            ULONG state, ULONG value);
  431.   /* Function updates the state of 3D engine. The updated state
  432.   // will take effect from the next primitive being rendered
  433.   //
  434.   // Params:
  435.   //    pFuncStruct     pointer to current instance of renderer
  436.   //                    as created by S3DTK_CreateRenderer
  437.   //    state           KEY identifying one of the possible
  438.   //                    3D engine status entries, see list at
  439.   //                    beginning of header
  440.   //    value           content depends on state value passed to
  441.   //                    function
  442.   */
  443.  
  444.   /* Get 3D engine states */
  445.   ULONG (* S3DTK_GetState)(S3DTK_LPFUNCTIONLIST pFuncStruct,
  446.                            ULONG state, void *value);
  447.   /* Function returns the current state of the 3D engine.
  448.   //
  449.   // Params:
  450.   //    pFuncStruct     see above
  451.   //    state           see S3DTK_SetState
  452.   //    value           for some state values this has to be
  453.   //                    a valid pointer to a structure in order
  454.   //                    to return function results
  455.   */
  456.  
  457.   /*** 2. 3D primitive functions
  458.   **** -------------------------
  459.   ***/
  460.  
  461.   /* Render primitives (triangles/lines) */
  462.   ULONG (* S3DTK_TriangleSet)(S3DTK_LPFUNCTIONLIST pFuncStruct,
  463.                               void **ppVertexSet,
  464.                               ULONG NumVertices, ULONG SetType);
  465.   /* This call causes the S3D engine to render the specified type
  466.   // of primitives.
  467.   //
  468.   // Params:
  469.   //    pFuncStruct     see above
  470.   //    ppVertexSet     points to an array of vertex pointers 
  471.   //                        (S3DTK_VERTEX_xxx)
  472.   //    NumVertices     number of entries in this array
  473.   //    SetType         type of primitive to be rendered (see above)
  474.   */
  475.  
  476.   /* Render primitives (triangles/lines), extended call */
  477.   ULONG (* S3DTK_TriangleSetEx)(S3DTK_LPFUNCTIONLIST pFuncStruct,
  478.                                 void **pVertexSet, ULONG NumVertices,
  479.                                 ULONG SetType, 
  480.                                 ULONG *pSetState, ULONG NumStates);
  481.   /* like S3DTK_TriangleSet, but sets S3D engine to specified state
  482.   // before rendering primitives
  483.   //
  484.   // Params:
  485.   //    pFuncStruct     see above
  486.   //    ppVertexSet     see above
  487.   //    NumVertices     see above
  488.   //    SetType         see above
  489.   //    pSetState       points to an array of ULONG value pairs,
  490.   //                    alternatig ULONG key; ULONG value which have
  491.   //                    the same meaning as in the S3DTK_SetState function.
  492.   //    NumStates       number of *pairs* in this array
  493.   */
  494.  
  495.   /*** 3. 2D primitive functions
  496.   **** -------------------------
  497.   ***/
  498.  
  499.   /* Copy a rect area inside video memory */
  500.   ULONG (* S3DTK_BitBlt)(S3DTK_LPFUNCTIONLIST pFuncStruct, 
  501.                          S3DTK_LPSURFACE pDestSurface, 
  502.                          S3DTK_LPRECTAREA pDestRect,
  503.                          S3DTK_LPSURFACE pSrcSurface, 
  504.                          S3DTK_LPRECTAREA pSrcRect);
  505.   /* This function copies the rectangle area from video memory defined
  506.   // by the second parameter set to the location in the video
  507.   // memory defined by the first parameter set.
  508.   //
  509.   // Params:
  510.   //    pFuncStruct     see above
  511.   //    pDestSurface    destination surface 
  512.   //    pDestRect       destination rectangle (no stretching possible)
  513.   //    pSrcSurface     source surface
  514.   //    pSrcRect        source rectangle
  515.   */
  516.  
  517.   /* copy a rect area inside video memory with screen door transparency */
  518.   ULONG (* S3DTK_BitBltTransparent)(S3DTK_LPFUNCTIONLIST pFuncStruct, 
  519.                                     S3DTK_LPSURFACE pDestSurface, 
  520.                                     S3DTK_LPRECTAREA pDestRect,
  521.                                     S3DTK_LPSURFACE pSrcSurface, 
  522.                                     S3DTK_LPRECTAREA pSrcRect,
  523.                                     ULONG TranspColor);
  524.   /* This function causes the rectangle area from video memory defined
  525.   // by the second parameter set to be copied to the location in the video
  526.   // memory defined by the first parameter set. If a source pixel color is
  527.   // equal to the color defined by TransparentColor the destination
  528.   // pixel will not be updated. Color format for transparent color matches
  529.   // the surfaces' color format.
  530.   //
  531.   // Params:
  532.   //    pFuncStruct     see above
  533.   //    pDestSurface    destination surface 
  534.   //    pDestRect       destination rectangle (no stretching possible)
  535.   //    pSrcSurface     source surface
  536.   //    pSrcRect        source rectangle
  537.   //    TranspColor     transparent color
  538.   */
  539.  
  540.   /* fill a rect area in video memory with color */
  541.   ULONG (* S3DTK_RectFill)(S3DTK_LPFUNCTIONLIST pFuncStruct,
  542.                            S3DTK_LPSURFACE pDestSurface,
  543.                            S3DTK_LPRECTAREA pDestRect,
  544.                            ULONG FillColor);
  545.  
  546.   /* This function fills the specified area in video memory with
  547.   // the given color. The color format of FillColor matches the
  548.   // current surface format.
  549.   //
  550.   // Params:
  551.   //    pFuncStruct     see above
  552.   //    pDestSurface    destination surface 
  553.   //    pDestRect       destination rectangle (no stretching possible)
  554.   //    FillColor       color used for filling
  555.   */
  556.  
  557.   /*** 4. Initialization and service functions
  558.   **** ---------------------------------------
  559.   ****/
  560.  
  561.   /* return lats error occurred inside toolkit library */
  562.   int (* S3DTK_GetLastError)(S3DTK_LPFUNCTIONLIST pFuncStruct);
  563.   /* This function returns the code of the last error if it
  564.   // is called immediately after the function that returned S3DTK_ERR.
  565.   //
  566.   // Params:
  567.   //    pFuncStruct     see above
  568.   */
  569.  
  570. #ifndef WIN32
  571.   /*** 5. Hardware stretching function (DOS only)
  572.   **** ------------------------------------------
  573.   ****/
  574.  
  575.   ULONG (* S3DTK_StretchDisplaySurface)(S3DTK_LPFUNCTIONLIST pFuncStruct,
  576.                                         ULONG width0, ULONG height0, 
  577.                                         ULONG width1, ULONG height1);
  578.   /* Stretch the surface pointed by pDisplaySurface to width by height.
  579.   // This function is supported in DOS only. Use DirectDraw functions in Win95.
  580.   //
  581.   // Params:
  582.   //    pFuncStruct     see above
  583.   //    width0          width of display area before stretching
  584.   //    height0         height of display area before stretching
  585.   //    width1          width of display area after being stretched
  586.   //    height1         height of display area after being stretched
  587.   */
  588. #endif /* not for WIN32 */
  589.  
  590. } S3DTK_FUNCTIONLIST;
  591.  
  592. /*** S3DTK_PhysicalToLinear
  593. ***/
  594. DllExport S3DTK_PhysicalToLinear(ULONG PhysAddr, ULONG Size);
  595. /* Maps given physical address and the size of the physical
  596. // memory area to linear address.
  597. // Caution: In a multi-threading environment linear address is valid
  598. // only in the calling thread's memory context.
  599. //
  600. // Params:
  601. //      PhysAddr    physical address (usually device address in
  602. //                      386 4GB address space)
  603. //      Size        size of the area to be mapped
  604. // Return:
  605. //      Linear address or S3DTK_ERR
  606. */
  607.  
  608. /*** S3DTK_LinearToPhysical
  609. ***/
  610. DllExport S3DTK_LinearToPhysical(ULONG Linear);
  611. /* Finds a physical address being mapped on the given linear
  612. // address.
  613. //
  614. // Params:
  615. //      Linear      linear address in the current thread's memory context
  616. // Return:
  617. //      Physical address or S3DTK_ERR
  618. */
  619.  
  620. /*** S3DTK_EnterCritical
  621. ***/
  622. DllExport S3DTK_EnterCritical(void);
  623. /* Serializes access to shared resources in WIN95 multi-thread
  624. // environment.
  625. // Function is for serializing an access to S3 2D/3D engine
  626. // among 32bit threads and WIN95 GUI subsystem. The call
  627. // to the function either permit the current thread to enter
  628. // the following code section or put the thread on hold until
  629. // the thread owing the section will call S3DTK_ReleaseCritical.
  630. //
  631. // Return:
  632. //      S3DTK_OK if it is successful.
  633. //      S3DTK_ERR if sharing mechanism isn't in place.
  634. */
  635.  
  636. /*** S3DTK_ReleaseCritical
  637. ***/
  638. DllExport S3DTK_ReleaseCritical(void);
  639. /* Releases the critical section owned by the thread that issued
  640. // S3DTK_EnterCritical
  641. //
  642. // Return:
  643. //      S3DTK_OK.
  644. */
  645.  
  646. /*** S3DTK_InitLib
  647. ***/
  648. DllExport S3DTK_InitLib(S3DTK_LPLIB_INIT pInit);
  649. /* Init 2D/3D engine and Toolkit lobrary.
  650. // This function initializes the Toolkit library. Must be called
  651. // before using any other function of this toolkit.
  652. //
  653. // Params:
  654. //      pInit   pointer to S3DTK_LIB_INIT structure, NULL for
  655. //              default values
  656. //
  657. // Return:
  658. //      S3DTK_OK or one of the possible error codes (see list)
  659. */
  660.  
  661. /*** S3DTK_ExitLib
  662. ***/
  663. DllExport S3DTK_ExitLib(void);
  664. /* Clean up. Must be called before exiting the App.
  665. //
  666. // Return:
  667. //      S3DTK_OK
  668. */
  669.  
  670. /*** S3DTK_CreateRenderer
  671. ***/
  672. DllExport S3DTK_CreateRenderer(S3DTK_LPRENDERER_INITSTRUCT pInit,
  673.                                S3DTK_LPFUNCTIONLIST *ppFunctionList);
  674. /* This function creates a new instance of the rendering device and returns
  675. // a pointer to the list of S3DTK interface functions.
  676. //
  677. // Params:
  678. //      pInit           pointer to valid S3DTK_RENDERER_INITSTRUCT or
  679. //                      NULL for default values
  680. //      ppFunctionList  pointer to function list pointer, filled by
  681. //                      S3DTK_CreateRenderer
  682. //
  683. // Return:
  684. //      S3DTK_OK or one of the possible error codes (see list)
  685. */
  686.  
  687. /*** S3DTK_DestroyRenderer
  688. ***/
  689. DllExport S3DTK_DestroyRenderer(S3DTK_LPFUNCTIONLIST *ppFunctionList);
  690. /* Destroys the given instance of the rendering device.
  691. // Note: After this call ppFunctionList is invalid!
  692. //
  693. // Params:
  694. //      ppFunctionList  pointer to function list pointer
  695. //
  696. // Return:
  697. //      S3DTK_OK
  698. */
  699.  
  700. #ifdef __cplusplus
  701. }
  702. #endif
  703.  
  704. #endif /* __S3DTK_H */
  705.