home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warptlk3.zip / TOOLKIT / BETA / BOOK / GMTLKBAS.INF (.txt) < prev    next >
OS/2 Help File  |  1995-09-06  |  140KB  |  3,225 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ
  3.  
  4. First Edition 
  5.  
  6. The following paragraph does not apply to the United Kingdom or any country 
  7. where such provisions are inconsistent with local law:  INTERNATIONAL BUSINESS 
  8. MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY 
  9. KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
  10. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  Some states 
  11. do not allow disclaimer of express or implied warranties in certain 
  12. transactions, therefore, this statement may not apply to you. 
  13.  
  14. This publication could include technical inaccuracies or typographical errors. 
  15. Changes are periodically made to the information herein; these changes will be 
  16. incorporated in new editions of the publication. IBM may make improvements 
  17. and/or changes in the product(s) and/or the program(s) described in this 
  18. publication at any time. 
  19.  
  20. It is possible that this publication may contain reference to, or information 
  21. about, IBM products (machines and programs), programming, or services that are 
  22. not announced in your country.  Such references or information must not be 
  23. construed to mean that IBM intends to announce such IBM products, programming, 
  24. or services in your country. 
  25.  
  26. Requests for technical information about IBM products should be made to your 
  27. IBM authorized reseller or IBM marketing representative. 
  28.  
  29.  
  30. ΓòÉΓòÉΓòÉ 1.1. Copyright Notices ΓòÉΓòÉΓòÉ
  31.  
  32. COPYRIGHT LICENSE: 
  33.  
  34. (C) Copyright International Business Machines Corporation 1995.  All rights 
  35. reserved. 
  36. Note to U.S. Government Users - Documentation related to restricted rights - 
  37. Use, duplication or disclosure is subject to restrictions set forth in GSA ADP 
  38. Schedule Contract with IBM Corp. 
  39.  
  40.  
  41. ΓòÉΓòÉΓòÉ 1.2. Disclaimers ΓòÉΓòÉΓòÉ
  42.  
  43. References in this publication to IBM products, programs, or services do not 
  44. imply that IBM intends to make these available in all countries in which IBM 
  45. operates.  Any reference to an IBM product, program or service is not intended 
  46. to state or imply that only IBM's product, program, or service may be used. 
  47. Any functionally equivalent product, program, or service that does not infringe 
  48. any of IBM's intellectual property rights or other legally protectable rights 
  49. may be used instead of the IBM product, program, or service.  Evaluation and 
  50. verification of operation in conjunction with other products, programs, or 
  51. services, except those expressly designated by IBM, are the user's 
  52. responsibility. 
  53.  
  54. IBM may have patents or pending patent applications covering subject matter in 
  55. these programs and documentation.  The furnishing of these programs and 
  56. documentation does not give you any license to these patents.  You can send 
  57. license inquiries, in writing, to the IBM Director of Licensing, IBM 
  58. Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. 
  59.  
  60. Licensees of this program who wish to have information about it for the purpose 
  61. of enabling: (i) the exchange of information between independently created 
  62. programs and other programs (including this one) and (ii) the mutual use of the 
  63. information which has been exchanged, should contact IBM Corporation, 
  64. Department RM1A, GS00 N.W. 51st Street, Boca Raton, FL 33431, U.S.A.  Such 
  65. information may be available, subject to appropriate terms and conditions, 
  66. including in some cases, payment of a fee. 
  67.  
  68.  
  69. ΓòÉΓòÉΓòÉ 1.3. Trademarks ΓòÉΓòÉΓòÉ
  70.  
  71. The following terms are trademarks of the IBM Corporation in the United States 
  72. or other countries: 
  73.  
  74.    IBM 
  75.    OS/2 
  76.  
  77.  The following terms are trademarks of other companies: 
  78.  
  79.    3D Studio             Autodesk, Inc. 
  80.    BRender               Argonaut Technologies Limited 
  81.    Gravis GamePad        Advanced Gravis Technologies 
  82.    MacIntosh             Apple Computer, Inc. 
  83.    Pentium               Intel Corp. 
  84.    SuperFX               Argonaut Technologies Ltd. 
  85.    Windows               Microsoft Corporation 
  86.  
  87.  Other company, product, and service names may be trademarks or service marks 
  88.  of others. 
  89.  
  90.  
  91. ΓòÉΓòÉΓòÉ 1.4. OS/2 Warp and the BonusPak ΓòÉΓòÉΓòÉ
  92.  
  93. OS/2 Warp consists of the highly acclaimed, award-winning and totally cool 
  94. operating system, OS/2 Warp Version 3 and the BonusPak, a suite of productivity 
  95. applications. 
  96.  
  97. In this document, we may be discussing the functions and features of OS/2 Warp. 
  98. Whenever we refer to OS/2 Warp, keep in mind that OS/2 Warp currently ships in 
  99. two flavors: 
  100.  
  101.    1. There is OS/2 Warp (red spine on retail box) that uses your existing DOS 
  102.       and Windows.  This product runs a wide variety of DOS and OS/2 
  103.       applications and, if you have Windows installed on your system, you will 
  104.       be able to continue to run Windows applications. 
  105.  
  106.    2. There is OS/2 Warp (blue spine on retail box) that includes DOS and 
  107.       Windows applications support.  This product also runs a wide variety of 
  108.       DOS and OS/2 applications but also has WIN-OS/2-the support required to 
  109.       run most Windows applications. 
  110.  
  111.  Which product you choose depends on whether or not you currently have Windows 
  112.  installed and also depends on what types of applications you plan to run. 
  113.  
  114.  
  115. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ
  116.  
  117. Welcome to the world of entertainment development-brought to you by the IBM 
  118. Corporation.  We want you to know that IBM is committed to PC gaming.  So, 
  119. here's what we at IBM intend to do for you-the entertainment developer. 
  120.  
  121. We are providing you technical information about the new features specifically 
  122. for entertainment: 
  123.  
  124.      3D graphics 
  125.      Multiplayer networking 
  126.      Full-screen DIVE enhancements for video support 
  127.      Real-time MIDI and direct audio enhancements for audio support 
  128.      A joystick for OS/2 and for DOS sessions of OS/2 
  129.  
  130.  Just to name a few of the many new entertainment features you're probably 
  131.  already wanting to include in your own new game.  All these features are 
  132.  coming in a special new toolkit specifically for you:  the Entertainment 
  133.  Tools. 
  134.  
  135.  We'll help you find our IBM home page-just for gaming stuff-on the World Wide 
  136.  Web.  You'll be able to have gaming information at your fingertips. 
  137.  
  138.  
  139. ΓòÉΓòÉΓòÉ 2.1. World Wide Web ΓòÉΓòÉΓòÉ
  140.  
  141. IBM provides easy access to an Internet home page (server) on the World Wide 
  142. Web (WWW) that contains a growing library of support information, information 
  143. about available OS/2 applications, and sample code. 
  144.  
  145. Web Explorer 
  146.  
  147. The Web Explorer is being included in newer versions of OS/2 Warp and is also 
  148. available electronically.  To download to your PC, simply click on an icon that 
  149. is presented on the Gopher Server or IBM Home Page.  It downloads and installs 
  150. itself.  Web Explorer allows users to access the World Wide Web (WWW) through a 
  151. graphical user interface.  The WWW links resources together in an 
  152. easy-to-use-fashion. 
  153.  
  154. For example, a user can get a map of a country, click on a city to retrieve 
  155. information, see photographs, and read about current demographics.  With Web 
  156. Explorer, users traverse the Internet by moving from one document to another 
  157. using links or hyperlinks, and can save and annotate documents. 
  158.  
  159. OS/2 Games Home Page 
  160.  
  161. The OS/2 games home page became available on April 22, 1995, at: 
  162.  
  163.   http://www.austin.ibm.com/os2games
  164.  
  165. As an entertainment developer, be sure to ask about having your application 
  166. listed there.  Also ask about how you can supply demo code for users to 
  167. download and try. 
  168.  
  169.  
  170. ΓòÉΓòÉΓòÉ 2.2. Related Publications ΓòÉΓòÉΓòÉ
  171.  
  172. The following diagram provides an overview of the OS/2 Warp Technical Library. 
  173.  
  174. Books can be ordered by calling toll free 1-800-342-6672 weekdays between 8:00 
  175. a.m. and 8:00 p.m. (EST).  In Canada, call 1-800-465-4234. 
  176.  
  177.  
  178. ΓòÉΓòÉΓòÉ 2.3. Additional Games-Related Publications ΓòÉΓòÉΓòÉ
  179.  
  180. In additional to the current book you are reading, the following games-related 
  181. documentation is being provided for this Beta.  You can find them in the 
  182. subdirectory \TOOLKIT\BETA\BOOK. 
  183.  
  184.  Argonaut's BRender Technical Reference 
  185.     This book describes the Brender real-time, 3D graphics library, which has a 
  186.     comprehensive Application Programming Interface (API), for quick and easy 
  187.     3D development. 
  188.  
  189.  Argonaut's BRender Concise Guide 
  190.     This book describes the Brender Power Rendering System Application 
  191.     Programming Interface (API), shows how the components of the BRender system 
  192.     work as a whole, and gives some idea of the capabilities of this system. 
  193.  
  194.  Real-Time MIDI 
  195.     This book provides a discussion of the new real-time MIDI architecture and 
  196.     introduces the real-time MIDI application programming interface (API), 
  197.     including detailed descriptions of the real-time MIDI functions and 
  198.     associated data types. 
  199.  
  200.  Direct Audio Interface 
  201.     This book provides an overview of the direct-audio interface including 
  202.     descriptions of messages and associated data types. 
  203.  
  204.  READMEs 
  205.     For this Beta, installation information might be provided for samples as 
  206.     individual README files within the same subdirectory as the samples. 
  207.  
  208.  
  209. ΓòÉΓòÉΓòÉ 2.4. Using This Online Book ΓòÉΓòÉΓòÉ
  210.  
  211. Before you begin to use this online book, it would be helpful to understand how 
  212. you can: 
  213.  
  214.      Expand the Contents to see all available topics. 
  215.      Obtain additional information for a highlighted word or phrase. 
  216.      Use action bar choices. 
  217.  
  218.  How To Use the Contents 
  219.  
  220.  When the Contents window first appears, some topics have a plus (+) sign 
  221.  beside them.  The plus sign indicates that additional topics are available. 
  222.  
  223.  To expand the Contents if you are using a mouse, select the plus sign (+).  If 
  224.  you are using a keyboard, use the Up or Down Arrow key to highlight the topic, 
  225.  and press the plus key (+). 
  226.  
  227.  To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  228.  to highlight the topic, and then press Enter). 
  229.  
  230.  How To Obtain Additional Information 
  231.  
  232.  After you select a topic, the information for that topic appears in a window. 
  233.  Highlighted words or phrases indicate that additional information is 
  234.  available.  Notice that certain words in the following paragraph are 
  235.  highlighted in green letters, or in white letters on a black background. 
  236.  These are called hypertext terms.  If you are using a mouse, double-click on 
  237.  the highlighted word.  If you are using a keyboard, press the Tab key to move 
  238.  to the highlighted word, and then press the Enter key.  Additional information 
  239.  appears in a window. 
  240.  
  241.  How To Use Action Bar Choices 
  242.  
  243.  Several choices are available for managing information presented in the 
  244.  M-Control Program/2 Programming Reference.  There are three pull-down menus on 
  245.  the action bar:  the Services menu, the Options menu, and the Help menu. 
  246.  
  247.  The actions that are selectable from the Services menu operate on the active 
  248.  window currently displayed on the screen.  These actions include the 
  249.  following: 
  250.  
  251.  Bookmark 
  252.     Sets a place holder so you can retrieve information of interest to you. 
  253.  
  254.     When you place a bookmark on a topic, it is added to a list of bookmarks 
  255.     you have previously set.  You can view the list, and you can remove one or 
  256.     all bookmarks from the list.  If you have not set any bookmarks, the list 
  257.     is empty. 
  258.  
  259.     To set a bookmark, do the following: 
  260.  
  261.       1. Select a topic from the Contents. 
  262.  
  263.       2. When that topic appears, choose the Bookmark option from the Services 
  264.          menu. 
  265.  
  266.       3. If you want to change the name used for the bookmark, type the new 
  267.          name in the field. 
  268.  
  269.       4. Select the Place radio button (or press the Up or Down Arrow key to 
  270.          select it). 
  271.  
  272.       5. Select OK.  The bookmark is then added to the bookmark list. 
  273.  
  274.  Search 
  275.     Finds occurrences of a word or phrase in the current topic, selected 
  276.     topics, or all topics. 
  277.  
  278.     You can specify a word or phrase to be searched.  You can also limit the 
  279.     search to a set of topics by first marking the topics in the Contents list. 
  280.  
  281.     To search for a word or phrase in all topics, do the following: 
  282.  
  283.       1. Choose the Search option from the Services pull-down. 
  284.  
  285.       2. Type the word or words to be searched. 
  286.  
  287.       3. Select All sections. 
  288.  
  289.       4. Select Search to begin the search. 
  290.  
  291.       5. The list of topics where the word or phrase appears is displayed. 
  292.  
  293.  Print 
  294.     Prints one or more topics.  You can also print a set of topics by first 
  295.     marking the topics in the Contents list. 
  296.  
  297.     You can print one or more topics.  You can also print a set of topics by 
  298.     first marking the topics on the Contents list. 
  299.  
  300.     To print the document Contents list, do the following: 
  301.  
  302.       1. Select Print from the Services menu. 
  303.  
  304.       2. Select Contents. 
  305.  
  306.       3. Select Print. 
  307.  
  308.       4. The Contents list is printed on your printer. 
  309.  
  310.  Copy 
  311.     Copies a topic you are viewing to a file you can edit. 
  312.  
  313.     You can copy a topic you are viewing into a temporary file named TEXT.TMP. 
  314.     You can later edit that file by using an editor such as the System Editor. 
  315.  
  316.     To copy a topic, do the following: 
  317.  
  318.       1. Expand the Contents list and select a topic. 
  319.  
  320.       2. When the topic appears, select Copy to file from the Services menu. 
  321.  
  322.     The system copies the text pertaining to that topic into the temporary 
  323.     TEXT.TMP file. 
  324.  
  325.     For information on any of the other choices in the Services menu, highlight 
  326.     the choice and press the F1 key. 
  327.  
  328.  Options 
  329.     Changes the way the Contents is displayed. 
  330.  
  331.     You can control the appearance of the Contents list. 
  332.  
  333.     To expand the Contents and show all levels for all topics, select Expand 
  334.     all from the Options menu. 
  335.  
  336.     For information on any of the other choices in the Options menu, highlight 
  337.     the choice and press the F1 key. 
  338.  
  339.  
  340. ΓòÉΓòÉΓòÉ 3. OS/2 Warp Networking ΓòÉΓòÉΓòÉ
  341.  
  342. Warp network functions represent a standard application layer interface to OS/2 
  343. games for networked, multiplayer support. 
  344.  
  345. The Warp network functions will eventually be supporting multiple transports 
  346. such as TCP/IP, SPX/IPX, and OEM stacks.  The first implementation of Warp 
  347. network functions, however, is only using TCP/IP. 
  348.  
  349. Warp network functions define a well-known user data protocol (UDP) port just 
  350. for games.  The Warp networking game server (also sometimes referred to as the 
  351. daemon) monitors the well-known game port and routes packets received at this 
  352. port to the application. 
  353.  
  354. The TCP/IP Services file (\TCPIP\ETC\SERVICES) must be modified to include the 
  355. well-known game port entry.  The modification would look similar to the 
  356. following: 
  357.  
  358. GAMED        5022/UDP              #Well Known UDP based Game Port.
  359.  
  360.  
  361. ΓòÉΓòÉΓòÉ 3.1. OS/2 Warp Network Functions ΓòÉΓòÉΓòÉ
  362.  
  363. The following Warp network functions are provided. The APIs are exported from 
  364. WARPNET.DLL and are resolved by WARPNET.LIB.  The public header file WARPNET.H 
  365. defines all elements of the external interface, including data structures and 
  366. the following functions: 
  367.  
  368.      WarpNetInitialize 
  369.      WarpNetOpen 
  370.      WarpNetBroadcast 
  371.      WarpNetPackSend 
  372.      WarpNetPackRecv 
  373.      WarpNetClose 
  374.  
  375.  
  376. ΓòÉΓòÉΓòÉ <hidden> int - Syntax ΓòÉΓòÉΓòÉ
  377.  
  378. An integer value. 
  379.  
  380.  
  381. ΓòÉΓòÉΓòÉ <hidden> HEV - Syntax ΓòÉΓòÉΓòÉ
  382.  
  383. 32-bit value used as an event semaphore handle. 
  384.  
  385.  
  386. ΓòÉΓòÉΓòÉ <hidden> USHORT - Syntax ΓòÉΓòÉΓòÉ
  387.  
  388. Unsigned integer in the range 0 through 65 535. 
  389.  
  390. typedef unsigned long USHORT;
  391.  
  392.  
  393. ΓòÉΓòÉΓòÉ <hidden> ULONG - Syntax ΓòÉΓòÉΓòÉ
  394.  
  395. Unsigned integer in the range 0 through 4294967295. 
  396.  
  397. typedef unsigned long ULONG;
  398.  
  399.  
  400. ΓòÉΓòÉΓòÉ <hidden> BOOL - Syntax ΓòÉΓòÉΓòÉ
  401.  
  402. Boolean. 
  403.  
  404. Valid values are FALSE, which is 0, and TRUE, which is 1. 
  405.  
  406. typedef unsigned long BOOL;
  407.  
  408.  
  409. ΓòÉΓòÉΓòÉ <hidden> CHAR - Syntax ΓòÉΓòÉΓòÉ
  410.  
  411. Single-byte character. 
  412.  
  413. #define CHAR char
  414.  
  415.  
  416. ΓòÉΓòÉΓòÉ <hidden> VOID - Syntax ΓòÉΓòÉΓòÉ
  417.  
  418. No parameter. 
  419.  
  420. #define VOID void
  421.  
  422.  
  423. ΓòÉΓòÉΓòÉ <hidden> PSZ - Syntax ΓòÉΓòÉΓòÉ
  424.  
  425. Pointer to a null-terminated string. 
  426.  
  427. typedef unsigned char * PSZ;
  428.  
  429.  
  430. ΓòÉΓòÉΓòÉ <hidden> PULONG - Syntax ΓòÉΓòÉΓòÉ
  431.  
  432. Pointer to a ULONG. 
  433.  
  434.  
  435. ΓòÉΓòÉΓòÉ <hidden> PEAOP2 - Syntax ΓòÉΓòÉΓòÉ
  436.  
  437. Pointer to a ULONG. 
  438.  
  439.  
  440. ΓòÉΓòÉΓòÉ 3.1.1. WarpNetInitialize ΓòÉΓòÉΓòÉ
  441.  
  442.  
  443. ΓòÉΓòÉΓòÉ <hidden> WarpNetInitialize - Syntax ΓòÉΓòÉΓòÉ
  444.  
  445. This function initializes the application with the underlying transports used. 
  446. All applications using Warp networking should call this function first.  This 
  447. function initializes the application to use sockets by calling sock_init().  A 
  448. socket is a unique host identifier created by the concatenation of a port 
  449. identifier with a transmission control protocol/internet protocol (TCP/IP) 
  450. address. 
  451.  
  452. The sockets are stored in the per-process-instance space of WARPNET.DLL in a 
  453. data structure called pplayer. 
  454.  
  455. #include <warpnet.h>
  456.  
  457. APIRET APIENTRY WarpNetInitialize (VOID)
  458.  
  459. If the initialization succeeds, two sockets are created: 
  460.  
  461.      A user data protocol (UDP) datagram socket. 
  462.      A transmission control protocol (TCP) stream socket. 
  463.  
  464.  
  465. ΓòÉΓòÉΓòÉ <hidden> WarpNetInitialize - Parameters ΓòÉΓòÉΓòÉ
  466.  
  467.  VOID 
  468.     No parameter. 
  469.  
  470.  
  471. ΓòÉΓòÉΓòÉ <hidden> WarpNetInitialize Return Value - rc ΓòÉΓòÉΓòÉ
  472.  
  473.  rc (ULONG) - returns 
  474.     Return codes indicating success or type of failure: 
  475.  
  476.  rc = 0 
  477.     Returns 0 if successful. 
  478.  
  479.  rc = nonzero. 
  480.     Returns nonzero if not successful. 
  481.  
  482.  You should also refer to the TCP/IP programmer's guide for an explanation of 
  483.  TCP/IP error codes. 
  484.  
  485.  
  486. ΓòÉΓòÉΓòÉ <hidden> WarpNetInitialize - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  487.  
  488. TICTAC, the programming tutorial (sample), demonstrates how to use networking 
  489. functions to develop a multiplayer, networked game.  This sample uses the Warp 
  490. network functions to illustrate a 2-player TicTacToe game, where two players 
  491. play against each other. 
  492.  
  493. These networking support functions are referred to as OS/2 Warp network 
  494. functions.  The Warp networking functions will eventually support multiple 
  495. transports, such as TCP/IP, SPX/IPX, and OEM stacks.  Currently, only TCP/IP 
  496. transport is supported. 
  497.  
  498. This programming tutorial is located in 
  499. TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\WARPNET\TICTAC. 
  500.  
  501. You can start the programming tutorial by typing the programming tutorial name 
  502. (TICTAC.EXE) at the OS/2 command line: 
  503.  
  504.    tictac
  505.  
  506. Or by double-clicking on the TicTacToe icon. 
  507.  
  508. Hardware Requirements: 
  509.  
  510.      Machine capable of running OS/2 Warp with TCP/IP and communications 
  511.       hardware. 
  512.  
  513.  Software Requirements: 
  514.  
  515.      WARPNET.DLL 
  516.      WARPNET.H 
  517.      OS/2 TCP/IP Version 2.x or higher 
  518.      OS/2 Warp 3.0 or higher. 
  519.  
  520.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  521.  section. 
  522.  
  523.  
  524. ΓòÉΓòÉΓòÉ <hidden> WarpNetInitialize - Topics ΓòÉΓòÉΓòÉ
  525.  
  526. Select an item: 
  527.  
  528. Syntax
  529. Parameters
  530. Returns
  531. Programming Tutorial Code
  532.  
  533.  
  534. ΓòÉΓòÉΓòÉ 3.1.2. WarpNetOpen ΓòÉΓòÉΓòÉ
  535.  
  536.  
  537. ΓòÉΓòÉΓòÉ <hidden> WarpNetOpen - Syntax ΓòÉΓòÉΓòÉ
  538.  
  539. This function initiates communication with the game server.  This function 
  540. sends a WARPNET_REGISTER_PLAYER message to the server in the body of the 
  541. function, which causes the server to update its player list.  The player list 
  542. maps client addresses or sockets to unique player identifiers. 
  543.  
  544. #include <warpnet.h>
  545.  
  546. APIRET APIENTRY WarpNetOpen (ToAddress Server
  547.                              WarpNetPacket
  548.                              * ppacket)
  549.  
  550.  
  551. ΓòÉΓòÉΓòÉ <hidden> WarpNetOpen - Parameters ΓòÉΓòÉΓòÉ
  552.  
  553.  Server 
  554.     The Destination address can be specified as a domain name address or dotted 
  555.     decimal address.  The fDotted flag in the ToAddress data structure is set; 
  556.     then the address is interpreted as the dotted decimal notation (for 
  557.     example, 9.83.6.60).  If the fDotted flag is clear, then the address is 
  558.     interpreted as a domain name system (for example: 
  559.     meteor.m6nova.r3galaxy.orb). 
  560.  
  561.  WarpNetPacket 
  562.     Refer to the WarpNetPacket data type. 
  563.  
  564.  * ppacket 
  565.     A pointer to a WarpNetPacket structure. 
  566.  
  567.  
  568. ΓòÉΓòÉΓòÉ <hidden> WarpNetOpen Return Value - rc ΓòÉΓòÉΓòÉ
  569.  
  570.  rc (ULONG) - returns 
  571.     Return codes indicating success or type of failure: 
  572.  
  573.  rc = 0 
  574.     Returns 0 if successful. 
  575.  
  576.  rc = nonzero. 
  577.     Returns nonzero if not successful. 
  578.  
  579.  You should also refer to the TCP/IP programmer's guide for an explanation of 
  580.  TCP/IP error codes. 
  581.  
  582.  
  583. ΓòÉΓòÉΓòÉ <hidden> WarpNetOpen - Remarks ΓòÉΓòÉΓòÉ
  584.  
  585. The application after initializing itself with WarpNet, by invoking 
  586. WarpNetInitialize(), calls this function next to register itself with the game 
  587. server.  The application needs to specify the server's address in the ToAddress 
  588. structure.  The application should also pass a pointer to a WarpNetPacket for 
  589. return information. 
  590.  
  591.  
  592. ΓòÉΓòÉΓòÉ <hidden> WarpNetOpen - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  593.  
  594. TICTAC, the programming tutorial (sample), demonstrates how to use networking 
  595. functions to develop a multiplayer, networked game.  This sample uses the Warp 
  596. network functions to illustrate a 2-player TicTacToe game, where two players 
  597. play against each other. 
  598.  
  599. These networking support functions are referred to as OS/2 Warp network 
  600. functions.  The Warp networking functions will eventually support multiple 
  601. transports, such as TCP/IP, SPX/IPX, and OEM stacks.  Currently, only TCP/IP 
  602. transport is supported. 
  603.  
  604. This programming tutorial is located in 
  605. TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\WARPNET\TICTAC. 
  606.  
  607. You can start the programming tutorial by typing the programming tutorial name 
  608. (TICTAC.EXE) at the OS/2 command line: 
  609.  
  610.    tictac
  611.  
  612. Or by double-clicking on the TicTacToe icon. 
  613.  
  614. Hardware Requirements: 
  615.  
  616.      Machine capable of running OS/2 Warp with TCP/IP and communications 
  617.       hardware. 
  618.  
  619.  Software Requirements: 
  620.  
  621.      WARPNET.DLL 
  622.      WARPNET.H 
  623.      OS/2 TCP/IP Version 2.x or higher 
  624.      OS/2 Warp 3.0 or higher. 
  625.  
  626.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  627.  section. 
  628.  
  629.  
  630. ΓòÉΓòÉΓòÉ <hidden> WarpNetOpen - Topics ΓòÉΓòÉΓòÉ
  631.  
  632. Select an item: 
  633.  
  634. Syntax
  635. Parameters
  636. Returns
  637. Remarks
  638. Programming Tutorial Code
  639.  
  640.  
  641. ΓòÉΓòÉΓòÉ 3.1.3. WarpNetBroadcast ΓòÉΓòÉΓòÉ
  642.  
  643.  
  644. ΓòÉΓòÉΓòÉ <hidden> WarpNetBroadcast - Syntax ΓòÉΓòÉΓòÉ
  645.  
  646. This function broadcasts the data to all connected clients.  The player list 
  647. defines all clients or players known to the WARPNET game server. 
  648.  
  649. #include <warpnet.h>
  650.  
  651. APIRET APIENTRY WarpNetBroadcast ( WarpNetPacket
  652.                                    * ppacket)
  653.  
  654.  
  655. ΓòÉΓòÉΓòÉ <hidden> WarpNetBroadcast - Parameters ΓòÉΓòÉΓòÉ
  656.  
  657.  WarpNetPacket 
  658.     Refer to the WarpNetPacket data type. 
  659.  
  660.  * ppacket 
  661.     A pointer to a WarpNetPacket structure. 
  662.  
  663.  
  664. ΓòÉΓòÉΓòÉ <hidden> WarpNetBroadcast Return Value - rc ΓòÉΓòÉΓòÉ
  665.  
  666.  rc (ULONG) - returns 
  667.     Return codes indicating success or type of failure. 
  668.  
  669.  rc = 0 
  670.     Returns 0 if successful. 
  671.  
  672.  rc = nonzero. 
  673.     Returns nonzero if not successful. 
  674.  
  675.  You should also refer to the TCP/IP programmer's guide for an explanation of 
  676.  TCP/IP error codes. 
  677.  
  678.  
  679. ΓòÉΓòÉΓòÉ <hidden> WarpNetBroadcast - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  680.  
  681. TICTAC, the programming tutorial (sample), demonstrates how to use networking 
  682. functions to develop a multiplayer, networked game.  This sample uses the Warp 
  683. network functions to illustrate a 2-player TicTacToe game, where two players 
  684. play against each other. 
  685.  
  686. These networking support functions are referred to as OS/2 Warp network 
  687. functions.  The Warp networking functions will eventually support multiple 
  688. transports, such as TCP/IP, SPX/IPX, and OEM stacks.  Currently, only TCP/IP 
  689. transport is supported. 
  690.  
  691. This programming tutorial is located in 
  692. TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\WARPNET\TICTAC. 
  693.  
  694. You can start the programming tutorial by typing the programming tutorial name 
  695. (TICTAC.EXE) at the OS/2 command line: 
  696.  
  697.    tictac
  698.  
  699. Or by double-clicking on the TicTacToe icon. 
  700.  
  701. Hardware Requirements: 
  702.  
  703.      Machine capable of running OS/2 Warp with TCP/IP and communications 
  704.       hardware. 
  705.  
  706.  Software Requirements: 
  707.  
  708.      WARPNET.DLL 
  709.      WARPNET.H 
  710.      OS/2 TCP/IP Version 2.x or higher 
  711.      OS/2 Warp 3.0 or higher. 
  712.  
  713.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  714.  section. 
  715.  
  716.  
  717. ΓòÉΓòÉΓòÉ <hidden> WarpNetBroadcast - Topics ΓòÉΓòÉΓòÉ
  718.  
  719. Select an item: 
  720.  
  721. Syntax
  722. Parameters
  723. Returns
  724. Programming Tutorial Code
  725.  
  726.  
  727. ΓòÉΓòÉΓòÉ 3.1.4. WarpNetPackSend ΓòÉΓòÉΓòÉ
  728.  
  729.  
  730. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackSend - Syntax ΓòÉΓòÉΓòÉ
  731.  
  732. This function sends user data in 512-byte packets. The function determines the 
  733. number of packets necessary to transmit all of the user data, and then it 
  734. sequences, timestamps, checksums, and prepends the WARPNET header before 
  735. transmitting the packets to the destination. 
  736.  
  737. #include <warpnet.h>
  738.  
  739. APIRET APIENTRY WarpNetPackSend ( ToAddress Destination,
  740.                                   WarpNetPacket
  741.                                   * ppacket)
  742.  
  743.  
  744. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackSend - Parameters ΓòÉΓòÉΓòÉ
  745.  
  746.  Destination 
  747.     The Destination address can be specified as a domain name address or dotted 
  748.     decimal address.  The fDotted flag in the ToAddress data structure is set; 
  749.     then the address is interpreted as the dotted decimal notation (for 
  750.     example, 9.83.6.60).  If the fDotted flag is clear, then the address is 
  751.     interpreted as a domain name system (for example: 
  752.     meteor.m6nova.r3galaxy.orb). 
  753.  
  754.  WarpNetPacket 
  755.     Refer to the WarpNetPacket data type. 
  756.  
  757.  * ppacket 
  758.     A pointer to a WarpNetPacket structure. 
  759.  
  760.  
  761. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackSend Return Value - rc ΓòÉΓòÉΓòÉ
  762.  
  763.  rc (ULONG) - returns 
  764.     Return codes indicating success or type of failure: 
  765.  
  766.  rc = 0 
  767.     Returns 0 if successful. 
  768.  
  769.  rc = nonzero. 
  770.     Returns nonzero if not successful. 
  771.  
  772.  You should also refer to the TCP/IP programmer's guide for an explanation of 
  773.  TCP/IP error codes. 
  774.  
  775.  The Destination address can be specified as a domain name address or dotted 
  776.  decimal address.  The fDotted flag in the ToAddress data structure is set; 
  777.  then the address is interpreted as the dotted decimal notation (for example, 
  778.  9.83.6.60).  If the fDotted flag is clear, then the address is interpreted as 
  779.  a domain name system (for example: meteor.m6nova.r3galaxy.orb). 
  780.  
  781.  
  782. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackSend - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  783.  
  784. TICTAC, the programming tutorial (sample), demonstrates how to use networking 
  785. functions to develop a multiplayer, networked game.  This sample uses the Warp 
  786. network functions to illustrate a 2-player TicTacToe game, where two players 
  787. play against each other. 
  788.  
  789. These networking support functions are referred to as OS/2 Warp network 
  790. functions.  The Warp networking functions will eventually support multiple 
  791. transports, such as TCP/IP, SPX/IPX, and OEM stacks.  Currently, only TCP/IP 
  792. transport is supported. 
  793.  
  794. This programming tutorial is located in 
  795. TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\WARPNET\TICTAC. 
  796.  
  797. You can start the programming tutorial by typing the programming tutorial name 
  798. (TICTAC.EXE) at the OS/2 command line: 
  799.  
  800.    tictac
  801.  
  802. Or by double-clicking on the TicTacToe icon. 
  803.  
  804. Hardware Requirements: 
  805.  
  806.      Machine capable of running OS/2 Warp with TCP/IP and communications 
  807.       hardware. 
  808.  
  809.  Software Requirements: 
  810.  
  811.      WARPNET.DLL 
  812.      WARPNET.H 
  813.      OS/2 TCP/IP Version 2.x or higher 
  814.      OS/2 Warp 3.0 or higher. 
  815.  
  816.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  817.  section. 
  818.  
  819.  
  820. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackSend - Example Code ΓòÉΓòÉΓòÉ
  821.  
  822. The following example illustrates the invocation of this function. 
  823.  
  824. ToAddress        dest;         // Destination Address
  825. WarpNetPacket    *packet;      // User Data Packet
  826. CHAR             *pch;
  827.  
  828. // Allocate Memory
  829. DosAllocMem ( (PPVOID)&packet, HEADER_SIZE,
  830.               (ULONG) PAG_COMMIT | PAG_READ | PAG_WRITE) )
  831.  
  832. DosAllocMem ( (PPVOID)&(Header->pData), 2048,
  833.               (ULONG) PAG_COMMIT | PAG_READ | PAG_WRITE) )
  834.  
  835.    memset (&dest,0,sizeof(dest));
  836.    memset (packet,0,HEADER_SIZE);
  837.       dest.fDotted = TRUE;
  838.       dest.fUsePlayerID = FALSE;
  839.       strcpy (dest.Destination,"9.83.6.60");
  840.  
  841. /* Fill the user header portion of the data gram */
  842.  
  843. packet->fHeaderOnly = FALSE;
  844.    packet->Message = START_GAME;   // Application specific message
  845.                                    // (not interpreted by warpnet)
  846.    packet  ->DataSize = 2032;
  847.    memset (packet->pData,'2',2048);
  848.  
  849. // Send the Registraton Data to the server.
  850.  
  851. WarpNetPackSend (dest,packet);
  852.  
  853. The following example illustrates another different invocation of this 
  854. function. 
  855.  
  856. dest.fUsePlayerID = TRUE;   // Use the PlayerID to specify packet destination
  857. dest.PlayerID = 3;
  858.  
  859. packet->fHeaderOnly = TRUE; // No data, we will just transmit the header
  860. packet->DataSize = 0;
  861. packet->pData = NULL;
  862. packet->DataWord1 = Joystick.x;
  863. packet->DataWord2 = Joystick.y;
  864. packet->DataWord3 = Joystick.z;
  865. packet->Message = JOYSTICK_INPUT;
  866.  
  867. WarpNetPackSend (dest,packet);
  868.  
  869.  
  870. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackSend - Topics ΓòÉΓòÉΓòÉ
  871.  
  872. Select an item: 
  873.  
  874. Syntax
  875. Parameters
  876. Returns
  877. Programming Tutorial Code
  878. Example Code
  879.  
  880.  
  881. ΓòÉΓòÉΓòÉ 3.1.5. WarpNetPackRecv ΓòÉΓòÉΓòÉ
  882.  
  883.  
  884. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackRecv - Syntax ΓòÉΓòÉΓòÉ
  885.  
  886. This function receives data.  This function does the converse of 
  887. WarpNetPackSend and has to assemble n packets to fill up a user-receiving 
  888. buffer.  The application that calls WarpNetPackRecv is blocked on an event 
  889. semaphore until data is available.  All packets are actually received at the 
  890. network interface by the game server's receive thread.  The server looks at the 
  891. User header on the packet received, locates the local application (or the 
  892. player) entry in the player list, and posts the event semaphore. 
  893.  
  894. Recall that at the application side where receive is called, the caller is 
  895. blocked on the event semaphore. 
  896.  
  897. #include <warpnet.h>
  898.  
  899. APIRET APIENTRY WarpNetPackRecv ( char * pchbuf)
  900.  
  901.  
  902. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackRecv - Parameters ΓòÉΓòÉΓòÉ
  903.  
  904.  char 
  905.     Single-byte character. 
  906.  
  907.  * pchbuf 
  908.     Pointer to a user buffer. 
  909.  
  910.  
  911. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackRecv Return Value - rc ΓòÉΓòÉΓòÉ
  912.  
  913.  rc (ULONG) - returns 
  914.     Return codes indicating success or type of failure: 
  915.  
  916.  rc = 0 
  917.     Returns 0 if successful. 
  918.  
  919.  rc = nonzero. 
  920.     Returns nonzero if not successful. 
  921.  
  922.  You should also refer to the TCP/IP programmer's guide for an explanation of 
  923.  TCP/IP error codes. 
  924.  
  925.  
  926. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackRecv - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  927.  
  928. TICTAC, the programming tutorial (sample), demonstrates how to use networking 
  929. functions to develop a multiplayer, networked game.  This sample uses the Warp 
  930. network functions to illustrate a 2-player TicTacToe game, where two players 
  931. play against each other. 
  932.  
  933. These networking support functions are referred to as OS/2 Warp network 
  934. functions.  The Warp networking functions will eventually support multiple 
  935. transports, such as TCP/IP, SPX/IPX, and OEM stacks.  Currently, only TCP/IP 
  936. transport is supported. 
  937.  
  938. This programming tutorial is located in 
  939. TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\WARPNET\TICTAC. 
  940.  
  941. You can start the programming tutorial by typing the programming tutorial name 
  942. (TICTAC.EXE) at the OS/2 command line: 
  943.  
  944.    tictac
  945.  
  946. Or by double-clicking on the TicTacToe icon. 
  947.  
  948. Hardware Requirements: 
  949.  
  950.      Machine capable of running OS/2 Warp with TCP/IP and communications 
  951.       hardware. 
  952.  
  953.  Software Requirements: 
  954.  
  955.      WARPNET.DLL 
  956.      WARPNET.H 
  957.      OS/2 TCP/IP Version 2.x or higher 
  958.      OS/2 Warp 3.0 or higher. 
  959.  
  960.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  961.  section. 
  962.  
  963.  
  964. ΓòÉΓòÉΓòÉ <hidden> WarpNetPackRecv - Topics ΓòÉΓòÉΓòÉ
  965.  
  966. Select an item: 
  967.  
  968. Syntax
  969. Parameters
  970. Returns
  971. Programming Tutorial Code
  972.  
  973.  
  974. ΓòÉΓòÉΓòÉ 3.1.6. WarpNetClose ΓòÉΓòÉΓòÉ
  975.  
  976.  
  977. ΓòÉΓòÉΓòÉ <hidden> WarpNetClose - Syntax ΓòÉΓòÉΓòÉ
  978.  
  979. This function terminates communication with the game server. 
  980.  
  981. #include <warpnet.h>
  982.  
  983. APIRET APIENTRY WarpNetClose(VOID)
  984.  
  985.  
  986. ΓòÉΓòÉΓòÉ <hidden> WarpNetClose - Parameters ΓòÉΓòÉΓòÉ
  987.  
  988.  VOID 
  989.     No parameter. 
  990.  
  991.  
  992. ΓòÉΓòÉΓòÉ <hidden> WarpNetClose Return Value - rc ΓòÉΓòÉΓòÉ
  993.  
  994.  rc (ULONG) - returns 
  995.     Return codes indicating success or type of failure: 
  996.  
  997.  rc = 0 
  998.     Returns 0 if successful. 
  999.  
  1000.  rc = nonzero. 
  1001.     Returns nonzero if not successful. 
  1002.  
  1003.  You should also refer to the TCP/IP programmer's guide for an explanation of 
  1004.  TCP/IP error codes. 
  1005.  
  1006.  
  1007. ΓòÉΓòÉΓòÉ <hidden> WarpNetClose - Remarks ΓòÉΓòÉΓòÉ
  1008.  
  1009. This function de-registers itself with the Warp network subsystem.  The player 
  1010. ID stored internally in a per-process-instance data structure is used to 
  1011. identify the player.  The reason for doing this is we do not allow proxies on 
  1012. close (for example, to guard against player 1 trying to close player 2).  The 
  1013. application is merely required to call WarpNetClose as part of its exit 
  1014. procedure.  In the body of WarpNetClose, we send a WARPNET_DEREGISTER_PLAYER 
  1015. message to the server.  The server on receipt of this message updates its 
  1016. internal PLAYERLIST structure and broadcasts the list to other peers.  The 
  1017. player lists are kept in synchronization. 
  1018.  
  1019.  
  1020. ΓòÉΓòÉΓòÉ <hidden> WarpNetClose - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  1021.  
  1022. TICTAC, the programming tutorial (sample), demonstrates how to use networking 
  1023. functions to develop a multiplayer, networked game.  This sample uses the Warp 
  1024. network functions to illustrate a 2-player TicTacToe game, where two players 
  1025. play against each other. 
  1026.  
  1027. These networking support functions are referred to as OS/2 Warp network 
  1028. functions.  The Warp networking functions will eventually support multiple 
  1029. transports, such as TCP/IP, SPX/IPX, and OEM stacks.  Currently, only TCP/IP 
  1030. transport is supported. 
  1031.  
  1032. This programming tutorial is located in 
  1033. TOOLKIT\BETA\SAMPLES\ENTOOLKT\NETWORK\WARPNET\TICTAC. 
  1034.  
  1035. You can start the programming tutorial by typing the programming tutorial name 
  1036. (TICTAC.EXE) at the OS/2 command line: 
  1037.  
  1038.    tictac
  1039.  
  1040. Or by double-clicking on the TicTacToe icon. 
  1041.  
  1042. Hardware Requirements: 
  1043.  
  1044.      Machine capable of running OS/2 Warp with TCP/IP and communications 
  1045.       hardware. 
  1046.  
  1047.  Software Requirements: 
  1048.  
  1049.      WARPNET.DLL 
  1050.      WARPNET.H 
  1051.      OS/2 TCP/IP Version 2.x or higher 
  1052.      OS/2 Warp 3.0 or higher. 
  1053.  
  1054.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  1055.  section. 
  1056.  
  1057.  
  1058. ΓòÉΓòÉΓòÉ <hidden> WarpNetClose - Topics ΓòÉΓòÉΓòÉ
  1059.  
  1060. Select an item: 
  1061.  
  1062. Syntax
  1063. Parameters
  1064. Returns
  1065. Programming Tutorial Code
  1066.  
  1067.  
  1068. ΓòÉΓòÉΓòÉ 3.2. Warp Network Data Types ΓòÉΓòÉΓòÉ
  1069.  
  1070. This section describes data types in C language.  A data type name beginning 
  1071. with "P" (for example (PMCI_CONNECTOR_PARMS) is likely to be a pointer to 
  1072. another data type (in this instance, MCI_CONNECTOR_PARMS).  If no data type 
  1073. definition can be found in this section for a data type name "Pxxxxxx,", it 
  1074. becomes a pointer to the data type "xxxxxxx," for which a definition should be 
  1075. found.  The implicit type definition needed for such a pointer "Pxxxxxx" is: 
  1076.  
  1077.      typedef xxxxxx *Pxxxxxx
  1078.  
  1079.  
  1080. ΓòÉΓòÉΓòÉ 3.2.1. WarpNetPacket ΓòÉΓòÉΓòÉ
  1081.  
  1082. For WarpNet, external data structures are shown.  In the WarpNetPacket 
  1083. structure, data members are shared between the application and the Warp network 
  1084. system.  The data members PackSeq, chksum, Timestamp, PackMarker, and Reserved 
  1085. are intended for system internal usage.  Applications should not care about 
  1086. these members. 
  1087.  
  1088. Registration is done at WarpNetOpen() time by sending a WARPNET_REGISTER_PLAYER 
  1089. message to the system. 
  1090.  
  1091. typedef struct user_pack_header {
  1092. ULONG   Message;
  1093. ULONG   Node;
  1094. ULONG   Channel;
  1095. ULONG   srcPlayerId;
  1096. ULONG   tgtPlayerId;
  1097. ULONG   fHeaderOnly;
  1098. ULONG   DataWord1;
  1099. ULONG   DataWord2;
  1100. ULONG   DataWord3;
  1101. ULONG   DataWord4;
  1102. ULONG   DataSize;
  1103. CHAR    *pData;
  1104. ULONG   PackSeq;
  1105. ULONG   chksum;
  1106. ULONG   TimeStamp;
  1107. ULONG   PackMarker;
  1108. ULONG   Reserved;
  1109.  
  1110. } WarpNetPacket;
  1111.  
  1112.  
  1113. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - Message ΓòÉΓòÉΓòÉ
  1114.  
  1115.  Message 
  1116.     A Warp network message 
  1117.  
  1118.  
  1119. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - Node ΓòÉΓòÉΓòÉ
  1120.  
  1121.  Node 
  1122.     Packet Destination Node (currently unused). 
  1123.  
  1124.  
  1125. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - Channel ΓòÉΓòÉΓòÉ
  1126.  
  1127.  Channel 
  1128.     Packet Destination channel (currently unused). 
  1129.  
  1130.  
  1131. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - srcPlayerId ΓòÉΓòÉΓòÉ
  1132.  
  1133.  srcPlayerId 
  1134.     Packet Source Player ID 
  1135.  
  1136.  
  1137. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - tgtPlayerId ΓòÉΓòÉΓòÉ
  1138.  
  1139.  tgtPlayerId 
  1140.     Packet Destination Player 
  1141.  
  1142.  
  1143. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - fHeaderOnly ΓòÉΓòÉΓòÉ
  1144.  
  1145.  fHeaderOnly 
  1146.     Ignore Data and Transmit the header only 
  1147.  
  1148.  
  1149. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - DataWord1 ΓòÉΓòÉΓòÉ
  1150.  
  1151.  DataWord1 
  1152.     Optional Data Word for application use 
  1153.  
  1154.  
  1155. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - DataWord2 ΓòÉΓòÉΓòÉ
  1156.  
  1157.  DataWord2 
  1158.     Optional Data Word for application use 
  1159.  
  1160.  
  1161. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - DataWord3 ΓòÉΓòÉΓòÉ
  1162.  
  1163.  DataWord3 
  1164.     Optional Data Word for application use 
  1165.  
  1166.  
  1167. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - DataWord4 ΓòÉΓòÉΓòÉ
  1168.  
  1169.  DataWord4 
  1170.     Optional Data Word for application use 
  1171.  
  1172.  
  1173. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - DataSize ΓòÉΓòÉΓòÉ
  1174.  
  1175.  DataSize 
  1176.     Packet Data Size.  Should be set by the application to indicate the size of 
  1177.     the data packet to be transmitted. 
  1178.  
  1179.  
  1180. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - *pData ΓòÉΓòÉΓòÉ
  1181.  
  1182.  *pData 
  1183.     Packet Data.  The data pointer that points to the actual data. 
  1184.  
  1185.  
  1186. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - PackSeq ΓòÉΓòÉΓòÉ
  1187.  
  1188.  PackSeq 
  1189.     Fragmented Packet Sequence 
  1190.  
  1191.  
  1192. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - chksum ΓòÉΓòÉΓòÉ
  1193.  
  1194.  chksum 
  1195.     Fragmented Packet Checksum 
  1196.  
  1197.  
  1198. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - TimeStamp ΓòÉΓòÉΓòÉ
  1199.  
  1200.  TimeStamp 
  1201.     Fragmented Packet TimeStamp 
  1202.  
  1203.  
  1204. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - PackMarker ΓòÉΓòÉΓòÉ
  1205.  
  1206.  PackMarker 
  1207.     Fragmentation/ Assembly Aide 
  1208.  
  1209.  
  1210. ΓòÉΓòÉΓòÉ <hidden> WarpNetPacket - Reserved ΓòÉΓòÉΓòÉ
  1211.  
  1212.  Reserved 
  1213.     For System use 
  1214.  
  1215.  
  1216. ΓòÉΓòÉΓòÉ 3.2.2. WarpNetDest ΓòÉΓòÉΓòÉ
  1217.  
  1218. typedef struct _WarpNetDest {
  1219. BOOL    fDotted;
  1220. CHAR    Destination [255];
  1221. BOOL    fUsePlayerID;
  1222. ULONG   PlayerId;
  1223.  
  1224. } ToAddress;
  1225.  
  1226.  
  1227. ΓòÉΓòÉΓòÉ <hidden> WarpNetDest - fDotted ΓòÉΓòÉΓòÉ
  1228.  
  1229.  fDotted (BOOL) 
  1230.     Dotted decimal address 
  1231.  
  1232.  
  1233. ΓòÉΓòÉΓòÉ <hidden> WarpNetDest - Destination [255] ΓòÉΓòÉΓòÉ
  1234.  
  1235.  Destination [255] (CHAR) 
  1236.     PlayerIds usually map to application Destinations.  Existing PlayerIds can 
  1237.     be queried from the system. 
  1238.  
  1239.  
  1240. ΓòÉΓòÉΓòÉ <hidden> WarpNetDest - fUsePlayerID ΓòÉΓòÉΓòÉ
  1241.  
  1242.  fUsePlayerID (BOOL) 
  1243.     Use PlayerID instead of internet address 
  1244.  
  1245.  
  1246. ΓòÉΓòÉΓòÉ <hidden> WarpNetDest - PlayerId ΓòÉΓòÉΓòÉ
  1247.  
  1248.  PlayerId (ULONG) 
  1249.     The playerId value that identifies a player.  PlayerId is returned to the 
  1250.     application as receipt of successfull registration. 
  1251.  
  1252.  
  1253. ΓòÉΓòÉΓòÉ 3.2.3. PlayerInst ΓòÉΓòÉΓòÉ
  1254.  
  1255. Player Instances are identified by this structure: 
  1256.  
  1257. typedef struct _group {
  1258. int     cs;
  1259. int     strms;
  1260. ULONG   PlayerId;
  1261. HEV     PackRecvSem;
  1262. HEV     ConRecvSem;
  1263. BOOL    Local;
  1264. ULONG   ProcessId;
  1265. struct sockaddr_inclient;
  1266.  
  1267. } PlayerInst;
  1268.  
  1269.  
  1270. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - cs ΓòÉΓòÉΓòÉ
  1271.  
  1272.  cs 
  1273.     Client UDP DataGram Socket 
  1274.  
  1275.  
  1276. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - strms ΓòÉΓòÉΓòÉ
  1277.  
  1278.  strms 
  1279.     Client TCP Stream Socket 
  1280.  
  1281.  
  1282. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - PlayerId ΓòÉΓòÉΓòÉ
  1283.  
  1284.  PlayerId 
  1285.     Player Identification number 
  1286.  
  1287.  
  1288. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - PackRecvSem ΓòÉΓòÉΓòÉ
  1289.  
  1290.  PackRecvSem 
  1291.     WarpNetPackRecv Semaphore 
  1292.  
  1293.  
  1294. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - ConRecvSem ΓòÉΓòÉΓòÉ
  1295.  
  1296.  ConRecvSem 
  1297.     WarpNetConRecv Semaphore 
  1298.  
  1299.  
  1300. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - Local ΓòÉΓòÉΓòÉ
  1301.  
  1302.  Local 
  1303.     Local Process Flag 
  1304.  
  1305.  
  1306. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - ProcessId ΓòÉΓòÉΓòÉ
  1307.  
  1308.  ProcessId 
  1309.     Process ID 
  1310.  
  1311.  
  1312. ΓòÉΓòÉΓòÉ <hidden> PlayerInst - sockaddr_in client ΓòÉΓòÉΓòÉ
  1313.  
  1314.  sockaddr_in client 
  1315.     Client Address Information 
  1316.  
  1317.  
  1318. ΓòÉΓòÉΓòÉ <hidden> OS/2 Warp Network Messages ΓòÉΓòÉΓòÉ
  1319.  
  1320. The WarpNetPacket data member message identifies the application/system 
  1321. messages.  Certain system messages alter the system state. Application messages 
  1322. are merely delivered to the application without system interpretation. 
  1323.  
  1324. Messages for Warp network include: 
  1325.  
  1326.  #define  WARPNETERR_BASE 5000 
  1327.  #define  WARPNETMSG_BASE 4000 
  1328.  #define  WARPNET_REGISTER_PLAYER (WARPNETMSG_BASE + 1) 
  1329.  #define  WARPNET_DEREGISTER_PLAYER (WARPNETMSG_BASE + 2) 
  1330.  #define  WARPNET_QUERY_NUMPLAYERS (WARPNETMSG_BASE + 3) 
  1331.  #define  WARPNET_QUERY_PROTOCOL (WARPNETMSG_BASE + 4) 
  1332.  #define  WARPNET_QUERY_PLAYERLIST (WARPNETMSG_BASE + 5) 
  1333.  #define  WARPNET_CURRENT_PLAYERLIST (WARPNETMSG_BASE + 6) 
  1334.  #define  WARPNET_REGISTERATION_COMPLETE (WARPNETMSG_BASE + 7) 
  1335.  #define  WARPNET_ERR_INVALID_BUFFER_SIZE (WARPNETERR_BASE + 1) 
  1336.  #define  WARPNET_ERR_INVALID_DESTINATION (WARPNETERR_BASE + 2) 
  1337.  #define  WARPNET_ERR_INVALID_BUFFER (WARPNETERR_BASE + 3) 
  1338.  #define  WARPNET_ERR_MEMORY_EXHAUSTED (WARPNETERR_BASE + 4) 
  1339.  #define  WARPNET_ERR_SOCKET_INITIALIZATION (WARPNETERR_BASE + 5) 
  1340.  
  1341.  
  1342. ΓòÉΓòÉΓòÉ 4. OS/2 Joystick Device Driver ΓòÉΓòÉΓòÉ
  1343.  
  1344. The OS/2 Joystick Device Driver (GAMEDD.SYS) is a generic drive that is not 
  1345. designed to work with any particular type of joystick.  It can support any two 
  1346. standard joysticks, or one joystick with extended features, such as a hatch or 
  1347. throttle control. 
  1348.  
  1349. The driver simply reads the joystick port for position information and feeds 
  1350. that back to the game program at the appropriate time.  It is then up to your 
  1351. program to interpret the data correctly. 
  1352.  
  1353. The OS/2 Joystick Device Driver GAMEDD.SYS for OS/2 (or GAMEVDD.SYS for DOS) 
  1354. allows applications to communicate with the driver, which allows games running 
  1355. under OS/2 or DOS very efficient and reliable readings of the joystick port. 
  1356.  
  1357. The OS/2 Joystick Device Driver allows an OS/2 Warp application to access the 
  1358. machine's game port and provides a common interface for game port facilities in 
  1359. all OS/2 games and other applications. 
  1360.  
  1361. The driver provides an interface for reading the joysticks and for providing 
  1362. reliable joystick readings.  The Joystick functions are implemented within the 
  1363. OS/2 Joystick Device Driver. 
  1364.  
  1365. The IBM PC game port adapter provides a simple interface to joysticks and other 
  1366. similar analog devices.  The status of up to 4 analog and 4 digital signals is 
  1367. read through I/O port address 201h.  Two analog and two digital signals are 
  1368. commonly grouped together in the form of a dual axis joystick with two "fire" 
  1369. buttons.  Some modern joysticks use two axes for movement and an additional 
  1370. axis for throttle. 
  1371.  
  1372. Each analog and digital signal is assigned one bit in the game adapter port.  A 
  1373. low (binary zero) value for a bit connected to a joystick button is returned 
  1374. when that button is depressed.  Bits representing analog signals are 
  1375. implemented as one-shot outputs.  All one-shots are fired when the I/O port is 
  1376. written to and remain high until an RC timing circuit decays.  The variable 
  1377. position of each joystick axis provides the necessary resistance for this delay 
  1378. circuit.  If a joystick axis is not connected, the infinite resistance across 
  1379. that signal holds the one-shot high indefinitely. 
  1380.  
  1381. Determining the position of each joystick axis is done by measuring the 
  1382. duration of the high state for each one-shot.  Two methods are commonly used to 
  1383. measure this duration:  counting loop iterations and reading the hardware 
  1384. timer.  Although the iterative method is dependant on the speed of the 
  1385. processor, with proper calibration of each axis this limitation becomes 
  1386. irrelevant.  This is the method chosen to sample the game port adapter in this 
  1387. driver. 
  1388.  
  1389. The execution of a DOS application inside an OS/2 VDM is controlled by the 
  1390. operating system.  As just one of many tasks being handled by the scheduler, 
  1391. the DOS application can be switched away from at any moment to be returned to 
  1392. that point at some later time.  If this occurs when the joysticks are being 
  1393. read by either of the above two methods, the result is catastrophic.  In the 
  1394. case of the iterative method, the suspending of execution causes the sampling 
  1395. procedure to terminate early and return low values for all axes.  In the case 
  1396. of the timed sampling methods, the delay introduced by the suspension of 
  1397. execution has the opposite effect in that the value read from the timer chip is 
  1398. incorrectly high.  In either case, the effect the user sees is that of the 
  1399. joystick "flickering" from the correct position making the device unusable. 
  1400.  
  1401. One of the primary functions of this driver is to provide a remedy to this 
  1402. problem for DOS applications using the iterative sampling method.  Not only is 
  1403. this method of reading the port substantially more common, but providing a fix 
  1404. is also much more feasible (selectively returning fabricated values from an 
  1405. emulated timer chip could have other more dramatic side effects making this 
  1406. procedure inadvisable).  The solution is as simple as returning high-values to 
  1407. the DOS application for each of the one-shot outputs until the correct count 
  1408. has been reached.  The counts are determined as part of the normal sampling 
  1409. procedure inside the real-time clock timer handler. 
  1410.  
  1411. The OS/2 Joystick Device Driver has two main purposes: 
  1412.  
  1413.      To provide a standard interface for OS/2 game programmers to use the PC 
  1414.       joystick port in their products 
  1415.  
  1416.      To eliminate the joystick response "flicker" effect seen in many games 
  1417.       running under OS/2 
  1418.  
  1419.  The obvious other function of this driver is to define and implement an 
  1420.  interface.  The generic IOCtl interface was chosen as the method of 
  1421.  communication with the driver for its ability to transfer specific packets of 
  1422.  information to and from the application.  Because this component of the driver 
  1423.  is simpler than the "flicker" reduction component while also supplying a large 
  1424.  part of its functionality, it is discussed in detail first. 
  1425.  
  1426.  
  1427. ΓòÉΓòÉΓòÉ 4.1. Joystick Device Driver Functions ΓòÉΓòÉΓòÉ
  1428.  
  1429. Defining and implementing API functions for OS/2 applications is one of the 
  1430. primary functions of this driver.  After opening the device, applications 
  1431. communicate with the driver using the function DosDevIOCtl after opening the 
  1432. new GAME$ device.  Functions are provided for getting and setting device 
  1433. parameters, reading the state of the devices connected, and calibrating those 
  1434. devices. 
  1435.  
  1436. The driver samples the game port adapter inside the real-time clock timer 
  1437. handler.  This handler is registered with the operating system at device 
  1438. initialization and is called every 32 milliseconds thereafter.  It determines 
  1439. if the game adapter port requires sampling based on client demand and the 
  1440. current sampling rate. Client demand for the sampling procedure exists only if 
  1441. an OS/2 application has the device open or if a VDM is emulating the port. 
  1442.  
  1443. The joysticks connected are determined and calibrated as part of the device 
  1444. initialization.  These parameters can be modified by an OS/2 application or 
  1445. refreshed through a calibration IOCtl request. 
  1446.  
  1447. In addition to the standard device Read function, functions are also defined 
  1448. for returning the state of the device connected at the next button press or at 
  1449. the next timed read.  These functions block the calling process until the given 
  1450. event occurs when the process is run from inside the timer handler. 
  1451.  
  1452.  
  1453. ΓòÉΓòÉΓòÉ 4.2. Flicker Reduction ΓòÉΓòÉΓòÉ
  1454.  
  1455. The pre-emptive, multi-tasking nature of OS/2 can cause DOS applications 
  1456. reading the game adapter port to deduce incorrect positions for the joysticks 
  1457. connected and cause flickering.  The solution implemented in this driver to 
  1458. this problem is to regularly sample the game adapter port inside the physical 
  1459. device driver (PDD) and then return fabricated values to the DOS application 
  1460. that reflect that state.  With the logic for regularly sampling the port 
  1461. already in the PDD, all that must be done in that regard is to activate that 
  1462. procedure. 
  1463.  
  1464. Before any of this can be initiated, the first thing that must be done is to 
  1465. trap any access to the game port by the DOS application.  Any time I/O ports 
  1466. are to be trapped or emulated, an OS/2 virtual device driver (VDD) is required. 
  1467. The VDD works in conjunction with the PDD to provide the device emulation by 
  1468. capturing port reads and returning values that reflect the current state as 
  1469. determined by the PDD.  The VDD is also responsible for determining if a given 
  1470. VDM is to have direct access to the port and if so, to obtain ownership of it. 
  1471.  
  1472. At device initialization, the VDD first opens the PDD and then retrieves a 
  1473. pointer to the data area that is to be used to store the current state of the 
  1474. device.  Then, the next item for the VDD is when a DOS session is started at 
  1475. which time it hooks the I/O port for the game adapter.  Knowing that the device 
  1476. must be written to by the CPU to fire the one-shots before the read sequence 
  1477. can begin, the hook handler for the Write operation is the function where 
  1478. device ownership or emulation is resolved. 
  1479.  
  1480. If the GAME_DIRECT_ACCESS for DOS property is ON for that session, this 
  1481. specifies that the device is to be directly accessed by the VDM.  In this case, 
  1482. the VDD must first obtain ownership of the device before allowing this 
  1483. operation to proceed.  Device ownership is one of the more complex issues 
  1484. handled by this driver.  It first involves getting permission from the PDD that 
  1485. can only be granted if the device is presently unused either by an OS/2 
  1486. application or by another VDM through the emulation system.  If not available, 
  1487. the user is given the choice to kill the session, wait for the device to become 
  1488. free, or ignore that error and use the device in emulation mode.  If the user 
  1489. chooses to wait for the device to become free, the DOS session process will be 
  1490. blocked on an event semaphore to be posted when the device is available. 
  1491.  
  1492. Once the VDD is granted ownership of the device by the PDD, it then must 
  1493. arbitrate final ownership among all the VDMs competing for it.  A mutual 
  1494. exclusion (MUTEX) semaphore is used as the final decision maker in this process 
  1495. and the VDM that is granted ownership of it is given the same status as the 
  1496. game adapter port.  When the DOS application, which owns the device terminates, 
  1497. the MUTEX semaphore is released allowing any other VDMs waiting to compete for 
  1498. its ownership once again.  If no VDMs are waiting, the ownership of the device 
  1499. is returned to none through a call to the PDD. 
  1500.  
  1501. If the GAME_DIRECT_ACCESS property for a VDM is in its default state of OFF and 
  1502. the game adapter port is written to, the emulation system is activated.  First 
  1503. the VDD informs the PDD that it wants to become a client of the sampling 
  1504. procedure.  If no other clients are already active, this request forces an 
  1505. initial sampling so that valid data is immediately available to the VDD.  Next 
  1506. the VDD copies the game port data from the PDD space to its own VDM instance 
  1507. data area using the pointer retrieved at initialization.  This copy of the data 
  1508. is used when the DOS application reads the game port. 
  1509.  
  1510. Next, the emulation system uses the other DOS property registered at 
  1511. initialization: "GAME_DIGITAL_RESPONSE."  If set to "ON," the joysticks 
  1512. connected are emulated as fixed resistance style joysticks such as the Gravis 
  1513. GamePad.  In this case, the values for each axis are selected from a field in 
  1514. the PDD data area that corresponds to the range the actual value is presently 
  1515. within.  That is, if the current value for an axis is less than the upper limit 
  1516. for the lower range, a given fixed value for the lower range is chosen. 
  1517.  
  1518. With the given value for each axis in hand, the VDD is ready to emulate the 
  1519. game port adapter when read by the DOS application.  First the count on the 
  1520. number of reads is zeroed as the last operation in the port Write handler. 
  1521. When the port read handler is called, the value for each axis is compared 
  1522. against the number of reads by this VDM and if greater, a 1 for that bit is 
  1523. generated.  The state of each position bit mirrors the value returned by the 
  1524. actual hardware when the PDD last sampled it on that iteration.  The bits for 
  1525. each of the buttons is retrieved from the PDD data area and used in generating 
  1526. the byte returned.  This information is transferred on each read to maintain a 
  1527. "freshness" in the button data. 
  1528.  
  1529. The driver needs to poll the game port for new joystick information.  However, 
  1530. it only does this when an application (game) is using it and is idle otherwise. 
  1531.  
  1532.  
  1533. ΓòÉΓòÉΓòÉ 4.3. Manual Installation of the Joystick Device Drivers ΓòÉΓòÉΓòÉ
  1534.  
  1535. NOTE:  If you have an older version of these drivers installed, you will have 
  1536. to delete the GAMEDD.SYS, GAMEVDD.SYS, and GAMEDD.DOC (if applicable) files 
  1537. from your \OS2 directory manually.  Also, modify references to these drivers 
  1538. from your CONFIG.SYS as explained in the following procedure. 
  1539.  
  1540. The Joystick Device Driver for OS/2 can be installed using the following steps: 
  1541.  
  1542.    1. Install the Entertainment Tools. 
  1543.  
  1544.       The Joystick Device Driver file (GAMEDD.SYS for OS/2) is copied to the 
  1545.       default directory \TOOLKIT\BETA\SYS\ unless you modify the Entertainment 
  1546.       Toolkit installation path. 
  1547.  
  1548.    2. Add the following line to your CONFIG.SYS file, which assumes you 
  1549.       installed to the default path: 
  1550.  
  1551.             device=d:\toolkit\beta\sys\gamedd.sys
  1552.  
  1553.       Be sure to replace d: with the letter of your boot drive. 
  1554.  
  1555.    3. Reboot your system to enable the driver. 
  1556.  
  1557.  
  1558. ΓòÉΓòÉΓòÉ 4.4. Known Compatibility List ΓòÉΓòÉΓòÉ
  1559.  
  1560. The following is a list of games that have been tested with this driver. 
  1561.  
  1562.  Name of Game             Version 
  1563.  Alien Carnage            1.0 
  1564.  Boppin                   1.1 
  1565.  Commander Keen           4.0 
  1566.  Doom II                  1.7 
  1567.  Falcon                   3.0 
  1568.  Jazz Jackrabbit          1.0 
  1569.  Line Wars II             1.04 
  1570.  Lion King                NA 
  1571.  Magic Carpet             NA 
  1572.  MS Flight Simulator      5.0a 
  1573.  Mortal Kombat            1.0 
  1574.  NASCAR Racing            NA 
  1575.  One Must Fall            1.0 
  1576.  Rampart                  NA 
  1577.  Raptor                   1.0 
  1578.  Star Control II          NA 
  1579.  SVGA Air Warrior         1.16b 
  1580.  Tie Fighter              NA 
  1581.  X-Wing 1 (3.5")          NA 
  1582.  
  1583.  
  1584. ΓòÉΓòÉΓòÉ 4.5. Known Limitations ΓòÉΓòÉΓòÉ
  1585.  
  1586. There are some games that do not work well work with joystick support under 
  1587. OS/2.  Unfortunately, the driver cannot do anything about fixing these 
  1588. problems.  Because the majority of games do work with a joystick under OS/2, we 
  1589. suggest you either contact the authors of the game in question, or use the OS/2 
  1590. Games Homepage (http://www.austin.ibm.com/os2game) to report problems you are 
  1591. having with a particular type of joystick. 
  1592.  
  1593. Because the driver is a general-purpose driver, it should work with almost any 
  1594. standard game adapter. 
  1595.  
  1596.  
  1597. ΓòÉΓòÉΓòÉ 4.6. OS/2 Joystick Device Driver Functions ΓòÉΓòÉΓòÉ
  1598.  
  1599. The OS/2 Joystick Device Driver (GAMEDD.SYS) allows an OS/2 Warp application to 
  1600. access the machine's game port.  The driver provides an interface or a set of 
  1601. function calls for reading the joysticks. 
  1602.  
  1603. The Joystick functions are implemented within the OS/2 Joystick Device Driver. 
  1604. Currently, there are no high level versions or access of these functions except 
  1605. through the function DosDevIOCtl.  The sample issues the function DosDevIOCtl 
  1606. to request status or send commands to the OS/2 Joystick Device Driver.  The API 
  1607. function numbers, input parameters to DosDevIOCtl, are defined by the OS/2 
  1608. Joystick Device Driver. 
  1609.  
  1610.  
  1611. ΓòÉΓòÉΓòÉ 4.6.1. DosOpen ΓòÉΓòÉΓòÉ
  1612.  
  1613.  
  1614. ΓòÉΓòÉΓòÉ <hidden> DosOpen - Syntax ΓòÉΓòÉΓòÉ
  1615.  
  1616. This function must be called first to open the device driver name (GAME$ ) 
  1617. prior to any function call to the OS/2 Joystick Device Driver.  When the 
  1618. program terminates, DosClose must be called to end the program properly. 
  1619.  
  1620. #include <os2.h>
  1621. #include <stdlib.h>
  1622. #include <iostream.h>
  1623. #include "joyos2.h"
  1624.  
  1625. APIRET DosOpen  ( PSZ pszFileName, PHFILE pHf,
  1626.                   PULONG pulAction, ULONG cbFile,
  1627.                   ULONG ulAttribute, ULONG fsOpenFlags,
  1628.                   ULONG fsOpenMode, PEAOP2 peaop2)
  1629.  
  1630.  
  1631. ΓòÉΓòÉΓòÉ <hidden> DosOpen - Parameters ΓòÉΓòÉΓòÉ
  1632.  
  1633.  pszFileName (PSZ) - input 
  1634.     Address of the ASCII path name of the device to be opened. 
  1635.  
  1636.  pHf (PHFILE) - output 
  1637.     Address of the handle for the file. 
  1638.  
  1639.  pulAction (PULONG) - output 
  1640.     Address of the variable that receives the value that specifies the action 
  1641.     taken by the DosOpen function. 
  1642.  
  1643.  cbFile (ULONG) - input 
  1644.     New logical size of the file (end of data, EOD), in bytes. 
  1645.  
  1646.  ulAttribute (ULONG) - input 
  1647.     File attribute information. 
  1648.  
  1649.  fsOpenFlags (ULONG) - input 
  1650.     The action to be taken depending on whether the file exists or does not 
  1651.     exist. 
  1652.  
  1653.  fsOpenMode (ULONG) - input 
  1654.     The mode of the open function. 
  1655.  
  1656.  peaop2 (PEAOP2) - input/output 
  1657.     Extended attribute. 
  1658.  
  1659.  A complete description of the DosOpen function can be found in the Control 
  1660.  Program Programming Reference. 
  1661.  
  1662.  
  1663. ΓòÉΓòÉΓòÉ <hidden> DosOpen Return Value - rc ΓòÉΓòÉΓòÉ
  1664.  
  1665.  rc (ULONG) - returns 
  1666.     Return codes indicating success or type of failure: 
  1667.  
  1668.  rc = 0 
  1669.     Returns 0 if successful. 
  1670.  
  1671.  rc = nonzero. 
  1672.     Returns nonzero if not successful. 
  1673.  
  1674.  A complete description of the DosOpen function can be found in the Control 
  1675.  Program Programming Reference. 
  1676.  
  1677.  
  1678. ΓòÉΓòÉΓòÉ <hidden> DosOpen - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  1679.  
  1680. JOYTEST, the OS/2 Joystick programming tutorial (sample), allows an OS/2 Warp 
  1681. application to access the machine's game port.  The design of this sample is 
  1682. based on the set of functions provided by the OS/2 Joystick device driver 
  1683. (GAMEDD.SYS).  The OS/2 Joystick device driver provides an interface or a set 
  1684. of function calls for reading the joysticks. 
  1685.  
  1686. This programming tutorial is located in 
  1687. TOOLKIT\BETA\SAMPLES\ENTOOLKT\INPUT\JOYTEST 
  1688.  
  1689. Hardware Requirements: 
  1690.  
  1691.      Joystick device. 
  1692.  
  1693.  Software Requirements: 
  1694.  
  1695.      GAMEDD.SYS driver 
  1696.      OS/2 Warp 3.0 or higher 
  1697.      OS/2 Warp Developer's Toolkit 3.0 or higher 
  1698.      IBM C Set ++ compiler 2.x or 3.x 
  1699.  
  1700.  You can start the programming tutorial by typing the programming tutorial name 
  1701.  (JOYTEST.EXE) at the OS/2 command line: 
  1702.  
  1703.      joytest
  1704.  
  1705.  Or by double-clicking on the Joystick icon. 
  1706.  
  1707.  Note:  Make sure the CONFIG.SYS has the following statement after installation 
  1708.  of the Entertainment Tools: 
  1709.  
  1710.   DEVICE=[drive:\] GAMEDD.SYS
  1711.  where drive: is the path pointing to GAMEDD.SYS. 
  1712.  
  1713.  There is user interaction to the sample by moving the joystick handle to 
  1714.  different position and the user will see the status information changing as 
  1715.  new values are being read in by the sample.  The user can press button 2 on 
  1716.  the joystick to see the count displayed. Depending on the number of installed 
  1717.  joysticks, the status and information of all joysticks will be shown similar 
  1718.  to the following: 
  1719.  
  1720.     Getting the current joystick values:
  1721.      A (x's, y's):     #x, #y
  1722.      A (x's, y's, z's) :  #x, #y #z  (when there is an extended joystick
  1723.                      installed)
  1724.     (where:
  1725.      #x = x-position value,
  1726.      #y = y-position value,
  1727.      #z = value for the hatch button, pedal or thrust control)
  1728.  
  1729.  If the driver is not installed, an error message is displayed and the program 
  1730.  terminates. 
  1731.  
  1732.  You might encounter the following messages while using the JOYTEST sample: 
  1733.  
  1734.  Error n:Program cannot open the device name 
  1735.  
  1736.  Check to see if the driver is installed on the system.  n is the error code 
  1737.  returned from the function call DosOpen. 
  1738.  
  1739.  Error n:Program cannot access the API function using the IOCtl interface 
  1740.  
  1741.  This error might be caused by a General Failure, buffer overflow or an 
  1742.  incorrect driver level.  n is the error code returned from the function call 
  1743.  DosDevIOCtl. 
  1744.  
  1745.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  1746.  section. 
  1747.  
  1748.  
  1749. ΓòÉΓòÉΓòÉ <hidden> DosOpen - Example Code ΓòÉΓòÉΓòÉ
  1750.  
  1751. The following example illustrates how to open the device. 
  1752.  
  1753. HFILE             hGame;
  1754. ULONG             action;
  1755. APIRET             rc;
  1756.  
  1757. rc = DosOpen ( GAMEPDDNAME, &hGame, &Action,
  1758.                0, FILE_READONLY, FILE_OPEN,
  1759.                OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE
  1760.  
  1761. rc = DosOpen ( GAMEPDDNAME,        /* "GAME$" */
  1762.         &hGame, &action,
  1763.         0,
  1764.         FILE_READONLY,
  1765.         FILE_OPEN,
  1766.         OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE,
  1767.         NULL);
  1768. if (rc != 0)
  1769. {
  1770.         /* ERROR opening device : result code in rc */
  1771. }
  1772.  
  1773.  
  1774. ΓòÉΓòÉΓòÉ <hidden> DosOpen - Topics ΓòÉΓòÉΓòÉ
  1775.  
  1776. Select an item: 
  1777.  
  1778. Syntax
  1779. Parameters
  1780. Returns
  1781. Programming Tutorial Code
  1782. Example Code
  1783.  
  1784.  
  1785. ΓòÉΓòÉΓòÉ 4.6.2. DosDevIOCtl ΓòÉΓòÉΓòÉ
  1786.  
  1787.  
  1788. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl - Syntax ΓòÉΓòÉΓòÉ
  1789.  
  1790. This function is used to access the OS/2 Joystick device driver's functions 
  1791. passing the unique device handle, hDevice, which is the returned value from 
  1792. DosOpen.  The category parameter has the value of hex 80. 
  1793.  
  1794. #include <os2.h>
  1795. #include <stdlib.h>
  1796. #include <iostream.h>
  1797. #include "joyos2.h"
  1798.  
  1799. APIRET DosDevIOCtl  ( HFILE hDevice, ULONG category,
  1800.                       ULONG function, PVOID pParams,
  1801.                       ULONG cbParmLenMax,
  1802.                       PULONG pcbParmLen, PVOID pData,
  1803.                       ULONG cbDataLenMax, PULONG pcbDataLen)
  1804.  
  1805.  
  1806. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl - Parameters ΓòÉΓòÉΓòÉ
  1807.  
  1808.  hDevice (HFILE) - input 
  1809.     Device handle returned by DosOpen. 
  1810.  
  1811.  category (ULONG) - input 
  1812.     Device category. 
  1813.  
  1814.  function (ULONG) - input 
  1815.     Device-specific function. 
  1816.  
  1817.  pParams (PVOID) - input 
  1818.     Address of the command-specific argument list. 
  1819.  
  1820.  cbParmLenMax (ULONG) - input 
  1821.     Length, in bytes, of pParams. 
  1822.  
  1823.  pcbParmLen (PULONG) - input 
  1824.     Pointer to the length of parameters. 
  1825.  
  1826.  pData (PVOID) - input 
  1827.     Address of the data area. 
  1828.  
  1829.  cbDataLenMax (ULONG) - input 
  1830.     Length, in bytes, of pData. 
  1831.  
  1832.  pcbDataLen (PULONG) - in/out 
  1833.     Pointer to the length of data. 
  1834.  
  1835.  A complete description of the DosDevIOCtl function can be found in the Control 
  1836.  Program Programming Reference. 
  1837.  
  1838.  
  1839. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl Return Value - rc ΓòÉΓòÉΓòÉ
  1840.  
  1841.  rc (ULONG) - returns 
  1842.     Return codes indicating success or type of failure: 
  1843.  
  1844.  rc = 0 
  1845.     Returns 0 if successful. 
  1846.  
  1847.  rc = nonzero 
  1848.     Returns nonzero if not successful 
  1849.  
  1850.  A complete description of the DosDevIOCtl function can be found in the Control 
  1851.  Program Programming Reference. 
  1852.  
  1853.  
  1854. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl - Example Code ΓòÉΓòÉΓòÉ
  1855.  
  1856. The following example illustrates how to call all the functions of the OS/2 
  1857. device driver: 
  1858.  
  1859. HFILE             hGame;
  1860. ULONG             action;
  1861. APIRET             rc;
  1862.  
  1863. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1864.                     GAME_GET_VERSION,
  1865.                     NULL, 0,
  1866.                     NULL, &version,
  1867.                     dataLen, &dataLen);
  1868.  
  1869. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1870.                     GAME_GET_PARMS,
  1871.                     NULL, 0,
  1872.                     NULL, &gameParms,
  1873.                     dataLen, &dataLen);
  1874.  
  1875. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1876.                     GAME_GET_CALIB,
  1877.                     NULL, 0,
  1878.                     NULL, &gameCalib,
  1879.                     dataLen, &dataLen);
  1880.  
  1881. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1882.                     GAME_GET_STATUS,
  1883.                     NULL, 0,
  1884.                     NULL, &gameStatus,
  1885.                     dataLen, &dataLen);
  1886.  
  1887. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1888.                     GAME_GET_STATUS_BUTWAIT,
  1889.                     NULL, 0,
  1890.                     NULL, &gameStatus,
  1891.                     dataLen, &dataLen)
  1892.  
  1893. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1894.                     GAME_SET_PARMS,
  1895.                     &gameParms, parmLen,
  1896.                     &parmLen, NULL,
  1897.                     0, NULL);
  1898.  
  1899. rc = DosDevIOCtl  ( hGame, IOCTL_CAT_USER,
  1900.                     GAME_GET_STATUS_SAMPWAIT,
  1901.                     NULL, 0,
  1902.                     NULL, &gameStatus,
  1903.                     dataLen, &dataLen);
  1904.  
  1905.  
  1906. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl - Function Numbers ΓòÉΓòÉΓòÉ
  1907.  
  1908. The function numbers for the functions are defined by the OS/2 Joystick device 
  1909. driver as follows: 
  1910.  
  1911.  #define IOCTL_CAT_USER 
  1912.     0x80   The category number. 
  1913.  
  1914.  #define GAME_GET_VERSION 
  1915.     0x01   Get version of the device driver. 
  1916.  
  1917.  #define GAME_GET_PARMS 
  1918.     0x02   Get device parameters. 
  1919.  
  1920.  #define GAME_SET_PARMS 
  1921.     0x03   Set device parameters. 
  1922.  
  1923.  #define GAME_GET_CALIB 
  1924.     0x04   Get the calibration values. 
  1925.  
  1926.  #define GAME_GET_STATUS 
  1927.     0x10   Get the current joystick status. 
  1928.  
  1929.  #define GAME_GET_STATUS_BUTWAIT 
  1930.     0x11   Get status at next button press. 
  1931.  
  1932.  #define GAME_GET_STATUS_SAMPWAIT 
  1933.     0x12   Get status until next sample. 
  1934.  
  1935.  
  1936. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  1937.  
  1938. JOYTEST, the OS/2 Joystick programming tutorial (sample), allows an OS/2 Warp 
  1939. application to access the machine's game port.  The design of this sample is 
  1940. based on the set of functions provided by the OS/2 Joystick device driver 
  1941. (GAMEDD.SYS).  The OS/2 Joystick device driver provides an interface or a set 
  1942. of function calls for reading the joysticks. 
  1943.  
  1944. This programming tutorial is located in 
  1945. TOOLKIT\BETA\SAMPLES\ENTOOLKT\INPUT\JOYTEST 
  1946.  
  1947. Hardware Requirements: 
  1948.  
  1949.      Joystick device. 
  1950.  
  1951.  Software Requirements: 
  1952.  
  1953.      GAMEDD.SYS driver 
  1954.      OS/2 Warp 3.0 or higher 
  1955.      OS/2 Warp Developer's Toolkit 3.0 or higher 
  1956.      IBM C Set ++ compiler 2.x or 3.x 
  1957.  
  1958.  You can start the programming tutorial by typing the programming tutorial name 
  1959.  (JOYTEST.EXE) at the OS/2 command line: 
  1960.  
  1961.      joytest
  1962.  
  1963.  Or by double-clicking on the Joystick icon. 
  1964.  
  1965.  Note:  Make sure the CONFIG.SYS has the following statement after installation 
  1966.  of the Entertainment Tools: 
  1967.  
  1968.   DEVICE=[drive:\] GAMEDD.SYS
  1969.  where drive: is the path pointing to GAMEDD.SYS. 
  1970.  
  1971.  There is user interaction to the sample by moving the joystick handle to 
  1972.  different position and the user will see the status information changing as 
  1973.  new values are being read in by the sample.  The user can press button 2 on 
  1974.  the joystick to see the count displayed. Depending on the number of installed 
  1975.  joysticks, the status and information of all joysticks will be shown. 
  1976.  
  1977.  If the driver is not installed, an error message is displayed and the program 
  1978.  terminates. 
  1979.  
  1980.  You might encounter the following messages while using the JOYTEST sample: 
  1981.  
  1982.  Error n:Program cannot open the device name 
  1983.  
  1984.  Check to see if the driver is installed on the system.  n is the error code 
  1985.  returned from the function call DosOpen. 
  1986.  
  1987.  Error n:Program cannot access the API function using the IOCtl interface 
  1988.  
  1989.  This error might be caused by a General Failure, buffer overflow or an 
  1990.  incorrect driver level.  n is the error code returned from the function call 
  1991.  DosDevIOCtl. 
  1992.  
  1993.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  1994.  section. 
  1995.  
  1996.  
  1997. ΓòÉΓòÉΓòÉ <hidden> DosDevIOCtl - Topics ΓòÉΓòÉΓòÉ
  1998.  
  1999. Select an item: 
  2000.  
  2001. Syntax
  2002. Parameters
  2003. Returns
  2004. Function Numbers
  2005. Programming Tutorial Code
  2006. Example Code
  2007.  
  2008.  
  2009. ΓòÉΓòÉΓòÉ 4.6.3. DosClose ΓòÉΓòÉΓòÉ
  2010.  
  2011.  
  2012. ΓòÉΓòÉΓòÉ <hidden> DosClose - Syntax ΓòÉΓòÉΓòÉ
  2013.  
  2014. This function is issued to end the program properly when the program 
  2015. terminates. 
  2016.  
  2017. #include <os2.h>
  2018. #include <stdlib.h>
  2019. #include <iostream.h>
  2020. #include "joyos2.h"
  2021.  
  2022. APIRET DosClose ( HFILE hFile )
  2023.  
  2024.  
  2025. ΓòÉΓòÉΓòÉ <hidden> DosClose - Parameters ΓòÉΓòÉΓòÉ
  2026.  
  2027.  hFile (HFILe) - input 
  2028.     The handle returned by a previous call to DosOpen. 
  2029.  
  2030.  A complete description of the DosClose function can be found in the Control 
  2031.  Program Programming Reference. 
  2032.  
  2033.  
  2034. ΓòÉΓòÉΓòÉ <hidden> DosClose Return Value - rc ΓòÉΓòÉΓòÉ
  2035.  
  2036.  rc (ULONG) - returns 
  2037.     Return codes indicating success or type of failure: 
  2038.  
  2039.  rc = 0 
  2040.     Returns 0 if successful. 
  2041.  
  2042.  rc = nonzero 
  2043.     Returns nonzero if not successful. 
  2044.  
  2045.  A complete description of the DosClose function can be found in the Control 
  2046.  Program Programming Reference. 
  2047.  
  2048.  
  2049. ΓòÉΓòÉΓòÉ <hidden> DosClose - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  2050.  
  2051. JOYTEST, the OS/2 Joystick programming tutorial (sample), allows an OS/2 Warp 
  2052. application to access the machine's game port.  The design of this sample is 
  2053. based on the set of functions provided by the OS/2 Joystick device driver 
  2054. (GAMEDD.SYS).  The OS/2 Joystick device driver provides an interface or a set 
  2055. of function calls for reading the joysticks. 
  2056.  
  2057. This programming tutorial is located in 
  2058. TOOLKIT\BETA\SAMPLES\ENTOOLKT\INPUT\JOYTEST 
  2059.  
  2060. Hardware Requirements: 
  2061.  
  2062.      Joystick device. 
  2063.  
  2064.  Software Requirements: 
  2065.  
  2066.      GAMEDD.SYS driver 
  2067.      OS/2 Warp 3.0 or higher 
  2068.      OS/2 Warp Developer's Toolkit 3.0 or higher 
  2069.      IBM C Set ++ compiler 2.x or 3.x 
  2070.  
  2071.  You can start the programming tutorial by typing the programming tutorial name 
  2072.  (JOYTEST.EXE) at the OS/2 command line: 
  2073.  
  2074.      joytest
  2075.  
  2076.  Or by double-clicking on the Joystick icon. 
  2077.  
  2078.  Note:  Make sure the CONFIG.SYS has the following statement after installation 
  2079.  of the Entertainment Tools: 
  2080.  
  2081.   DEVICE=[drive:\] GAMEDD.SYS
  2082.  where drive: is the path pointing to GAMEDD.SYS. 
  2083.  
  2084.  There is user interaction to the sample by moving the joystick handle to 
  2085.  different position and the user will see the status information changing as 
  2086.  new values are being read in by the sample.  The user can press button 2 on 
  2087.  the joystick to see the count displayed. Depending on the number of installed 
  2088.  joysticks, the status and information of all joysticks will be shown. 
  2089.  
  2090.  If the driver is not installed, an error message is displayed and the program 
  2091.  terminates. 
  2092.  
  2093.  You might encounter the following messages while using the JOYTEST sample: 
  2094.  
  2095.  Error n:Program cannot open the device name 
  2096.  
  2097.  Check to see if the driver is installed on the system.  n is the error code 
  2098.  returned from the function call DosOpen. 
  2099.  
  2100.  Error n:Program cannot access the API function using the IOCtl interface 
  2101.  
  2102.  This error might be caused by a General Failure, buffer overflow or an 
  2103.  incorrect driver level.  n is the error code returned from the function call 
  2104.  DosDevIOCtl. 
  2105.  
  2106.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  2107.  section. 
  2108.  
  2109.  
  2110. ΓòÉΓòÉΓòÉ <hidden> DosClose - Example Code ΓòÉΓòÉΓòÉ
  2111.  
  2112. The following example illustrates how to terminate access to the the game: 
  2113.  
  2114. HFILE             hGame;
  2115. ULONG             action;
  2116. APIRET             rc;
  2117.  
  2118. rc = DosClose  ( hGAME )
  2119.  
  2120.  
  2121. ΓòÉΓòÉΓòÉ <hidden> DosClose - Topics ΓòÉΓòÉΓòÉ
  2122.  
  2123. Select an item: 
  2124.  
  2125. Syntax
  2126. Parameters
  2127. Returns
  2128. Programming Tutorial Code
  2129. Example Code
  2130.  
  2131.  
  2132. ΓòÉΓòÉΓòÉ 4.7. OS/2 Joystick Device Driver Data Types ΓòÉΓòÉΓòÉ
  2133.  
  2134. This section describes data types in C language.  A data type name beginning 
  2135. with "P" (for example (PMCI_CONNECTOR_PARMS) is likely to be a pointer to 
  2136. another data type (in this instance, MCI_CONNECTOR_PARMS).  If no data type 
  2137. definition can be found in this section for a data type name "Pxxxxxx,", it 
  2138. becomes a pointer to the data type "xxxxxxx," for which a definition should be 
  2139. found.  The implicit type definition needed for such a pointer "Pxxxxxx" is: 
  2140.  
  2141.      typedef xxxxxx *Pxxxxxx
  2142.  
  2143.  
  2144. ΓòÉΓòÉΓòÉ 4.7.1. GAME_STATUS_STRUCT ΓòÉΓòÉΓòÉ
  2145.  
  2146. The status structure for the current data of all joysticks as well as the 
  2147. number of times each button being pressed since the last read. 
  2148.  
  2149. typedef struct {
  2150. GAME_DATA_STRUCT   curdata;
  2151.           USHORT   b1cnt;
  2152.           USHORT   b2cnt;
  2153.           USHORT   b3cnt;
  2154.           USHORT   b4cnt;
  2155.  
  2156. } GAME_STATUS_STRUCT;
  2157.  
  2158.  
  2159. ΓòÉΓòÉΓòÉ <hidden> GAME_STATUS_STRUCT Field - curdata ΓòÉΓòÉΓòÉ
  2160.  
  2161.  curdata 
  2162.     Current status 
  2163.  
  2164.  
  2165. ΓòÉΓòÉΓòÉ <hidden> GAME_STATUS_STRUCT Field - b1cnt ΓòÉΓòÉΓòÉ
  2166.  
  2167.  b1cnt (USHORT) 
  2168.     Count of button 1 press. 
  2169.  
  2170.  
  2171. ΓòÉΓòÉΓòÉ <hidden> GAME_STATUS_STRUCT Field - b2cnt ΓòÉΓòÉΓòÉ
  2172.  
  2173.  b2cnt (USHORT) 
  2174.     Count of button 2 press. 
  2175.  
  2176.  
  2177. ΓòÉΓòÉΓòÉ <hidden> GAME_STATUS_STRUCT Field - b3cnt ΓòÉΓòÉΓòÉ
  2178.  
  2179.  b3cnt (USHORT) 
  2180.     Count of button 3 press. 
  2181.  
  2182.  
  2183. ΓòÉΓòÉΓòÉ <hidden> GAME_STATUS_STRUCT Field - b4cnt ΓòÉΓòÉΓòÉ
  2184.  
  2185.  b4cnt (USHORT) 
  2186.     Count of button 4 press. 
  2187.  
  2188.  
  2189. ΓòÉΓòÉΓòÉ 4.7.2. GAME_PARM_STRUCT ΓòÉΓòÉΓòÉ
  2190.  
  2191. The parameter structure for parameters defining the operation of the driver and 
  2192. the information on the installed joysticks. 
  2193.  
  2194. {
  2195. typedef struct {
  2196. USHORT   useA;
  2197. USHORT   useB;
  2198. USHORT   mode;
  2199. USHORT   format;
  2200. USHORT   sampDiv;
  2201. USHORT   scale;
  2202. USHORT   res1;
  2203. USHORT   res2;
  2204. } GAME_PARM_STRUCT;
  2205.  
  2206.  
  2207. ΓòÉΓòÉΓòÉ <hidden> useA - Parameters ΓòÉΓòÉΓòÉ
  2208.  
  2209.  useA (USHORT) 
  2210.     Joystick A is installed. 
  2211.  
  2212.  
  2213. ΓòÉΓòÉΓòÉ <hidden> useB - Parameters ΓòÉΓòÉΓòÉ
  2214.  
  2215.  useB (USHORT) 
  2216.     Joystick B is installed. 
  2217.  
  2218.  
  2219. ΓòÉΓòÉΓòÉ <hidden> mode - Parameters ΓòÉΓòÉΓòÉ
  2220.  
  2221.  mode (USHORT) 
  2222.     Only timed sampling was implemented. 
  2223.  
  2224.  
  2225. ΓòÉΓòÉΓòÉ <hidden> format - Parameters ΓòÉΓòÉΓòÉ
  2226.  
  2227.  format (USHORT) 
  2228.     Only raw format was implemented. 
  2229.  
  2230.  
  2231. ΓòÉΓòÉΓòÉ <hidden> sampDiv - Parameters ΓòÉΓòÉΓòÉ
  2232.  
  2233.  sampDiv (USHORT) 
  2234.     Samp freq = 32 / n. 
  2235.  
  2236.  
  2237. ΓòÉΓòÉΓòÉ <hidden> scale - Parameters ΓòÉΓòÉΓòÉ
  2238.  
  2239.  scale (USHORT) 
  2240.     Scaling factor. 
  2241.  
  2242.  
  2243. ΓòÉΓòÉΓòÉ <hidden> res1 - Parameters ΓòÉΓòÉΓòÉ
  2244.  
  2245.  res1 (USHORT) 
  2246.     Must be 0. 
  2247.  
  2248.  
  2249. ΓòÉΓòÉΓòÉ <hidden> res2 - Parameters ΓòÉΓòÉΓòÉ
  2250.  
  2251.  res2 (USHORT) 
  2252.     Must be 0. 
  2253.  
  2254.  
  2255. ΓòÉΓòÉΓòÉ 4.7.3. GAME_CALIB_STRUCT ΓòÉΓòÉΓòÉ
  2256.  
  2257. The structure defines the calibration values of each axis: 
  2258.  
  2259.      Upper limit on value to be considered in lower range 
  2260.      Center value 
  2261.      Lower limit on value to be considered in upper range 
  2262.  
  2263.   typedef struct {
  2264.   GAME_3POS_STRUCT  Ax;
  2265.   GAME_3POS_STRUCT  Ay;
  2266.   GAME_3POS_STRUCT  Bx;
  2267.   GAME_3POS_STRUCT  By;
  2268.  
  2269.   } GAME_CALIB_STRUCT;
  2270.  
  2271.  
  2272. ΓòÉΓòÉΓòÉ <hidden> GAME_3POS_STRUCT Ax - Parameters ΓòÉΓòÉΓòÉ
  2273.  
  2274. GAME_3POS_STRUCT  Ax; 
  2275.  
  2276.  GAME_3POS_STRUCT  Ax; 
  2277.  
  2278.  
  2279. ΓòÉΓòÉΓòÉ <hidden> GAME_3POS_STRUCT  Ay - Parameters ΓòÉΓòÉΓòÉ
  2280.  
  2281.  GAME_3POS_STRUCT  Ay; 
  2282.  
  2283.  
  2284. ΓòÉΓòÉΓòÉ <hidden> GAME_3POS_STRUCT  Bx - Parameters ΓòÉΓòÉΓòÉ
  2285.  
  2286.  GAME_3POS_STRUCT  Bx; 
  2287.  
  2288.  
  2289. ΓòÉΓòÉΓòÉ <hidden> GAME_3POS_STRUCT  By - Parameters ΓòÉΓòÉΓòÉ
  2290.  
  2291.  GAME_3POS_STRUCT  By; 
  2292.  
  2293.  
  2294. ΓòÉΓòÉΓòÉ 4.7.4. GAME_DATA_STRUCT ΓòÉΓòÉΓòÉ
  2295.  
  2296. The structure defines the instantaneous state of the joysticks and all buttons. 
  2297.  
  2298. typedef struct {
  2299. GAME_2DPOS_STRUCT A;
  2300. GAME_2DPOS_STRUCT B;
  2301. USHORT   butMask;
  2302.  
  2303. } GAME_DATA_STRUCT;
  2304.  
  2305.  
  2306. ΓòÉΓòÉΓòÉ <hidden> GAME_2DPOS_STRUCT A - Parameters ΓòÉΓòÉΓòÉ
  2307.  
  2308.  GAME_2DPOS_STRUCT A 
  2309.  
  2310.  
  2311. ΓòÉΓòÉΓòÉ <hidden> GAME_2DPOS_STRUCT B - Parameters ΓòÉΓòÉΓòÉ
  2312.  
  2313.  GAME_2DPOS_STRUCT B 
  2314.  
  2315.  
  2316. ΓòÉΓòÉΓòÉ <hidden> butMask - Parameters ΓòÉΓòÉΓòÉ
  2317.  
  2318.  butMask (USHORT) 
  2319.  
  2320.  
  2321. ΓòÉΓòÉΓòÉ 4.7.5. GAME_2DPOS_STRUCT ΓòÉΓòÉΓòÉ
  2322.  
  2323. The structure defines the 2-D position for each joystick. 
  2324.  
  2325. typedef USHORT GAME_POS {
  2326. GAME_POS x;
  2327. GAME_POS y;
  2328.  
  2329. } GAME_2DPOS_STRUCT;
  2330.  
  2331. typedef SHORT GAME_POS
  2332.  
  2333.  
  2334. ΓòÉΓòÉΓòÉ <hidden> GAME_POS x - Parameters ΓòÉΓòÉΓòÉ
  2335.  
  2336.  GAME_POS x (USHORT) 
  2337.     Some data formats require signed values. 
  2338.  
  2339.  
  2340. ΓòÉΓòÉΓòÉ <hidden> GAME_POS y - Parameters ΓòÉΓòÉΓòÉ
  2341.  
  2342.  GAME_POS y (USHORT) 
  2343.     Some data formats require signed values. 
  2344.  
  2345.  
  2346. ΓòÉΓòÉΓòÉ 4.7.6. GAME_3DPOS_STRUCT ΓòÉΓòÉΓòÉ
  2347.  
  2348. The structure to be used for calibration and digital response on each axis. 
  2349.  
  2350. typedef struct {
  2351. GAME_POS lower;
  2352. GAME_POS centre;
  2353. GAME_POS upper;
  2354.  
  2355. } GAME_3POS_STRUCT;
  2356.  
  2357.  
  2358. ΓòÉΓòÉΓòÉ <hidden> GAME_POS lower ΓòÉΓòÉΓòÉ
  2359.  
  2360.  GAME_POS lower 
  2361.     The lower calibration value for an extended joystick. 
  2362.  
  2363.  
  2364. ΓòÉΓòÉΓòÉ <hidden> GAME_POS center ΓòÉΓòÉΓòÉ
  2365.  
  2366.  GAME_POS center 
  2367.     The center calibration value for an extended joystick. 
  2368.  
  2369.  
  2370. ΓòÉΓòÉΓòÉ <hidden> GAME_POS upper ΓòÉΓòÉΓòÉ
  2371.  
  2372.  GAME_POS upper 
  2373.     The upper calibration value for an extended joystick. 
  2374.  
  2375.  
  2376. ΓòÉΓòÉΓòÉ 5. DIVE and Full-Screen DIVE ΓòÉΓòÉΓòÉ
  2377.  
  2378. Software motion video implementation under OS/2 has attained sizable 
  2379. performance advantages by enabling video decompressors to directly write to 
  2380. video memory.  While this technique provides good performance, it has the 
  2381. disadvantage that each decompressor must deal with the pel format of the 
  2382. display in various modes, clipping the output to visible regions, and any 
  2383. scaling that is to be performed. Additionally, on bank-switched video displays, 
  2384. the decompressor must return on partial frames to enable the video stream 
  2385. handler to switch banks. 
  2386.  
  2387. The Direct Interface Video Extensions (DIVE) give OS/2 Warp applications direct 
  2388. access to the PC video hardware and also provide a high level of performance. 
  2389. DIVE allows you to generate the high-speed graphics needed for today's advanced 
  2390. multimedia software. 
  2391.  
  2392. The new DIVE interface for displaying images permits high-speed animation from 
  2393. still image data.  High speed can mean 50fps or more-depending on the image 
  2394. size, whether acceleration hardware is available, and what type of display is 
  2395. used. 
  2396.  
  2397. OS/2 Warp supports several ways of addressing the video display, and the 
  2398. following are especially interesting to you as a game developer.  Using DIVE 
  2399. functions, applications can either: 
  2400.  
  2401.      Use the DIVE functions if you want your application to take advantage of 
  2402.       any hardware accelerator support by using a pointer returned by DiveOpen 
  2403.       (refer to Direct Interface Video Extensions). 
  2404.  
  2405.       Or: 
  2406.  
  2407.      Write directly to video memory, even when running in a Presentation 
  2408.       Manager window, by using the enhanced DIVE (EnDIVE) architecture.  EnDIVE 
  2409.       supports the use of motion video accelerator hardware (refer to Direct 
  2410.       Access to Video Buffers). 
  2411.  
  2412.  
  2413. ΓòÉΓòÉΓòÉ 5.1. Direct Interface Video Extensions (DIVE) ΓòÉΓòÉΓòÉ
  2414.  
  2415. DIVE provides optimized blitting performance for motion video subsystems and 
  2416. applications that perform rapid screen updates in the OS/2 PM and full-screen 
  2417. environments.  The DIVE blitter uses acceleration hardware when present and 
  2418. applicable to the function being performed. 
  2419.  
  2420. Information about DIVE functions includes: 
  2421.  
  2422.      DIVE Display Engine Function Characteristics 
  2423.  
  2424.       The DIVE display engine abstracts the low-level device driver DIVE 
  2425.       function (EnDIVE) to a higher level resulting in easy-to-use functions 
  2426.       for display updates and hides the complexities of color space conversion, 
  2427.       window clipping, scaling, and bank switching.  The DIVE display engine 
  2428.       detects and takes advantage of motion video acceleration hardware, when 
  2429.       present using EnDive, providing improved performance. 
  2430.      Dive Image Buffer 
  2431.  
  2432.       DIVE consolidates the complexities of dealing with direct video frame 
  2433.       buffer access (sometimes referred to as "direct access" or "black hole") 
  2434.       into a single DLL that enables efficient transfer to video memory with 
  2435.       clipping, scaling, and color space conversion.  The optimized screen 
  2436.       access functionality provided by DIVE can be used for motion video 
  2437.       display, fast image updates for interactive games, and fast screen 
  2438.       display by 3D graphics libraries. 
  2439.      Dive Palette 
  2440.  
  2441.       Of special interest to gamers, DIVE also simulates palette animation in 
  2442.       direct color display modes. 
  2443.      Direct Frame-Buffer Access 
  2444.  
  2445.       DIVE also uses graphics display hardware acceleration capabilities when 
  2446.       present so your game might actually run faster through the display engine 
  2447.       than it would with direct video buffer access. 
  2448.  
  2449.  For complete information about Direct Interface Video Extensions (DIVE), refer 
  2450.  to the Multimedia Programming Reference.  This reference is intended to be 
  2451.  used in conjunction with the Multimedia Application Programming Guide and 
  2452.  Multimedia Subsystem Programming Guide. 
  2453.  
  2454.  
  2455. ΓòÉΓòÉΓòÉ 5.1.1. DIVE Display Engine Function Characteristics ΓòÉΓòÉΓòÉ
  2456.  
  2457. The DIVE system-level interface abstracts the low-level device driver DIVE 
  2458. interface to a higher level and adds software emulation for operations that all 
  2459. DIVE users have had to do.  This system-level interface is referred to as the 
  2460. DIVE engine. 
  2461.  
  2462. The DIVE engine consists of a single, stand-alone DLL that exports the 
  2463. following functions: 
  2464.  
  2465.      Query for display capabilities 
  2466.      Open instance 
  2467.      Visible region specification 
  2468.      Allocation of image data buffers 
  2469.      Buffer-to-screen/buffer-to-buffer transfer (blitter) setup 
  2470.      8-bit CLUT color palette simulation/specification 
  2471.      Transfer buffer to image display/transfer buffer to buffer 
  2472.      Utility functions useful for direct access, including window 
  2473.       starting-address calculation 
  2474.      Frame buffer acquire/de-acquire 
  2475.      VRAM bank selection (for bank-switched displays) 
  2476.      Close instance 
  2477.  
  2478.  The display engine enables subsystem components (for example, video CODECs) 
  2479.  and applications to either directly access the video buffer or to use the 
  2480.  display engine screen transfer functions.  If direct access is used, the using 
  2481.  component or application is responsible for writing to the frame buffer format 
  2482.  for the current display mode and correctly clipping the output.  In addition, 
  2483.  the component is responsible for acquiring and bank switching the display 
  2484.  apertures.  If display engine screen transfer functions are used, the display 
  2485.  engine handles clipping, pel format and color space conversions, and any 
  2486.  necessary hardware serialization.  The input formats and their corresponding 
  2487.  color encoding specification values are: 
  2488.  
  2489.      CLUT 8 (256 color) - "LUT8" 
  2490.      8-bit greyscale - "GREY" 
  2491.      RGB 16 (5-6-5, 5-5-5) - "R565", "R555", "R664" 
  2492.      RGB 24 (R-G-B, B-G-R) - "RGB3", "BGR3" 
  2493.      RGB 32 (R-G-B, B-G-R) - "RGB4", "BGR4" 
  2494.      YUV 9 - DVI/Indeo three-plane color subsampled - "YUV9" 
  2495.      YUV 422 -  "Y422" 
  2496.      YUV CCIR601 - three-plane 2x2 color subsampled (MJPEG, MPEG) - "Y2X2" 
  2497.      YUV CCIR601 - three-plane 4x4 color subsampled  - "Y4X4" 
  2498.  
  2499.  The output formats are: 
  2500.  
  2501.      CLUT 8 (256 color) 
  2502.      RGB 16 (5-6-5, 5-5-5, 6-6-4) 
  2503.      RGB 24 (R-G-B, B-G-R) 
  2504.      RGB 32 (R-G-B-x,  B-G-R-x) 
  2505.      Blitter Operation 
  2506.  
  2507.  There are two main ways to use DIVE:  using the DIVE blitter and using 
  2508.  direct-frame buffer access.  DIVE applications gain access to DIVE functions 
  2509.  by obtaining a DIVE handle: 
  2510.  
  2511.       ULONG       ulErrorCode;
  2512.       HDIVE       *phDiveInst;
  2513.       BOOL        fNonScreenInstance;
  2514.       PPVOID      ppFrameBuffer;
  2515.  
  2516.       ulErrorCode = DiveOpen( *phDiveInst, fNonScreenInstance, ppFrameBuffer );
  2517.  
  2518.  A corresponding DiveClose function must be called at application termination. 
  2519.  If DIVE is to be used for blitting to the screen, set fNonScreenInstance to 
  2520.  FALSE.  Otherwise, if DIVE is to be used only for off-screen sizing or color 
  2521.  format conversion, set fNonScreenInstance to TRUE.  If fNonScreenInstance is 
  2522.  FALSE, a pointer to the frame buffer is returned in ppFrameBuffer. 
  2523.  
  2524.  
  2525. ΓòÉΓòÉΓòÉ 5.1.2. Dive Image Buffer ΓòÉΓòÉΓòÉ
  2526.  
  2527. Because DIVE will use off-screen VRAM where available for acceleration of 
  2528. blitting operations, the application should allocate all source blitting 
  2529. buffers from DIVE whenever possible.  To allocate a buffer, the application 
  2530. would make the following call: 
  2531.  
  2532.     ULONG   ulBufNum;
  2533.     FOURCC  fccColorSpace;
  2534.     ULONG   ulWidth, ulHeight, ulLineSizeBytes;
  2535.     PBYTE   pbImageBuffer;
  2536.  
  2537.     ulErrorCode = DiveAllocImageBuffer(
  2538.             hDive,                   /* DIVE handle             */
  2539.             &ulBufNum,               /* Buffer number (output)  */
  2540.             fccColorSpace,           /* Color format            */
  2541.             ulWidth, ulHeight,       /* Size of maximum image   */
  2542.             ulLineSizeBytes,
  2543.             &pbImageBuffer);
  2544.  
  2545. A corresponding DiveFreeImageBuffer function call is used to deallocate the 
  2546. buffer when it is no longer needed.  The color format of the image buffer is 
  2547. described by fccColorSpace. The DIVE interface defines constants for a variety 
  2548. of 8-, 16-, and 24-bit color encoding schemes.  After a buffer is allocated and 
  2549. before it can be used for blitting, it must be accessed as shown in the 
  2550. following example: 
  2551.  
  2552.     PBYTE   pbImageBuffer;
  2553.     ULONG   ulBufferScanLineBytes, ulBufferScanLines;
  2554.  
  2555.     ulErrorCode = DiveBeginImageBufferAccess(
  2556.             hDiveInst,                /* DIVE handle                  */
  2557.             ulBufferNumber,           /* Buffer number                */
  2558.             &pbImageBuffer,           /* Ptr to image buffer (output) */
  2559.             &ulBufferScanLineBytes);  /* Scan line length (output)    */
  2560.             &ulBufferScanLines);      /* Scan lines (output)          */
  2561.  
  2562. DIVE calculates the number of bytes per scan line for the image buffer (based 
  2563. on the color format) and returns the value in ulBufferScanLineBytes.  The 
  2564. application can now write color data into pbImageBuffer.  For example, the 
  2565. application could open a bit-map file and read the bit-map data directly into 
  2566. the image buffer.  After the data has been written, the application calls 
  2567. DiveEndImageBufferAccess to deaccess the buffer.  Be sure to use scan line 
  2568. bytes (you might have to read a line at a time). 
  2569.  
  2570.  
  2571. ΓòÉΓòÉΓòÉ 5.1.3. Dive Palette ΓòÉΓòÉΓòÉ
  2572.  
  2573. Applications must inform DIVE of the state of the physical palette upon 
  2574. initialization and whenever the physical palette changes.  At application 
  2575. initialization, and in response to a WM_REALIZEPALETTE message, the application 
  2576. calls the following sequence: 
  2577.  
  2578.     BYTE       pbPal[1024];
  2579.  
  2580.     /* Query the physical palette from PM   */
  2581.     GpiQueryRealColors( hps, 0, 0, 256, (PLONG)pbPal);
  2582.  
  2583.     /* Pass it to DIVE                      */
  2584.     DiveSetDestinationPalette( hDive, (PBYTE)pbPal);
  2585.  
  2586. If the application itself is using palettes, these palettes must also be 
  2587. communicated to DIVE through the DiveSetSourcePalette function. For example, if 
  2588. the application is using DIVE to blit 256-color palettized images to the 
  2589. screen, the application must send the image palette with a call to 
  2590. DiveSetSourcePalette.  If a sequence of images is being used for animation and 
  2591. the palette remains constant through the series, it is necessary to call 
  2592. DiveSetSourcePalette only once before blitting the first image in the series. 
  2593.  
  2594. DIVE provides high-speed screen updates by bypassing PM.  In order to maintain 
  2595. the integrity of the PM desktop, DIVE applications must notify DIVE whenever 
  2596. the visible region of the application window changes so that output may be 
  2597. clipped accordingly. 
  2598.  
  2599. Every DIVE application will request visible region notification at window 
  2600. initialization time with the following call: 
  2601.  
  2602.     WinSetVisibleRegionNotify( hwnd, TRUE);
  2603.  
  2604. The first parameter is the handle of the window where the graphics operations 
  2605. will appear, and the second parameter turns on notification for that window. 
  2606. (A corresponding WinSetVisibleRegionNotify(hwnd, FALSE) call should be made to 
  2607. turn notification off at window termination time.) 
  2608.  
  2609. Whenever the window's visible region begins to change, either because the 
  2610. window is being moved or sized or another window or icon overlaying the window 
  2611. is being moved or sized, the window will receive a WM_VRNDISABLED message.  In 
  2612. response to this message,  the DIVE application will call DiveSetupBlitter 
  2613. (hDiveInst, 0).  After the movement is complete, the window will receive a 
  2614. WM_VRNENABLED message.  In response to this message, the DIVE application will 
  2615. query the new visible region, using WinQueryVisibleRegion as follows: 
  2616.  
  2617.     hps = WinGetPS( hwnd );
  2618.     hrgn = GpiCreateRegion( hps, 0, NULL);
  2619.     WinQueryVisibleRegion( hwnd, hrgn);
  2620.  
  2621. Whenever the visible region, source color format, or image source or 
  2622. destination size changes, the DIVE application must pass the changes to DIVE 
  2623. with a call to DiveSetupBlitter.  Note that it is necessary to pass the 
  2624. rectangles for the region in window coordinates and the position of the window 
  2625. in desktop coordinates. 
  2626.  
  2627. First, get the rectangles and window coordinates: 
  2628.  
  2629.     RECTL   rctls[50];      /* Rectangles for visible rgn   */
  2630.     RGNRECT rgnCtl;         /* Region control struct        */
  2631.     SETUP_BLITTER   SetupBlitter;   /* DiveSetupBlitter struct      */
  2632.     POINTL  pointl;
  2633.     SWP     swp;
  2634.     HPS     hps;
  2635.     HRGN    hrgn;
  2636.  
  2637.     rgnCtl.ircStart = 0;    /* Enumerate rectangles */
  2638.     rgnCtl.crc = 50;        /* Starting with first  */
  2639.     rgnCtl.ulDirection = RECTDIR_LFRT_TOPBOT;
  2640.  
  2641.     /* Get rectangles for the visible region        */
  2642.     GpiQueryRegionRects( hps, hrgn, NULL, &rgnCtl, rctls);
  2643.  
  2644.     /* Find the window position relative to its parent.     */
  2645.     WinQueryWindowPos( hwnd, &swp );
  2646.  
  2647.     /* Map window position to the desktop.  */
  2648.     pointl.x = swp.x;
  2649.     pointl.y = swp.y;
  2650.     WinMapWindowPoints( WinQueryWindow( hwnd, QW_PARENT ),
  2651.             HWND_DESKTOP, &pointl, 1);
  2652.  
  2653. Then, pass the information to DIVE: 
  2654.  
  2655.     /* Tell DIVE about the new settings.  */
  2656.     SIZEL   sizlSrcImg;     /* Size of source image */
  2657.     FOURCC  fccSrcColors;   /* Source image format  */
  2658.  
  2659.     SetupBlitter.ulStructLen = sizeof ( SETUP_BLITTER );
  2660.     SetupBlitter.fInvert = 0;
  2661.     SetupBlitter.fccSrcColorFormat = fccSrcColors;
  2662.     SetupBlitter.ulSrcLineSizeBytes = ulScanLineBytes;
  2663.     SetupBlitter.ulSrcWidth = sizlSrcImg.cx;
  2664.     SetupBlitter.ulSrcHeight = sizlSrcImg.cy;
  2665.     SetupBlitter.ulSrcPosX = 0;
  2666.     SetupBlitter.ulSrcPosY = 0;
  2667.     SetupBlitter.fccDstColorFormat = FOURCC_SCRN;
  2668.     SetupBlitter.ulDstLineSizeBytes = 0;
  2669.     SetupBlitter.ulDstWidth = swp.cx;
  2670.     SetupBlitter.ulDstHeight = swp.cy;
  2671.     SetupBlitter.ulDstPosX = 0;
  2672.     SetupBlitter.ulDstPosY = 0;
  2673.     SetupBlitter.lScreenPosX = pointl.x;
  2674.     SetupBlitter.lScreenPosY = pointl.y;
  2675.     SetupBlitter.ulNumDstRects = rgnCtl.crcReturned;
  2676.     SetupBlitter.pVisDstRects = rctls;
  2677.     DiveSetupBlitter ( hDive, &SetupBlitter );
  2678.  
  2679. The color format of the source image is described by fccSrcColors. 
  2680.  
  2681. Note that, in this example, the DIVE blitter is set up to blit to the screen, 
  2682. but that need not be the case.  DIVE could also be used to perform color 
  2683. conversion and/or stretch blitting to a destination image.  The destination 
  2684. color-encoding format would be indicated in fccDstColorFormat; ulDstWidth and 
  2685. ulDstHeight would be set to the size of the destination image; ulNumDstRects 
  2686. would be set to 1; and pVisDstRects would point to a single rectangle with 
  2687. xLeft=yBottom=0 xRight=ulDstWidth and yTop=ulDstHeight. 
  2688.  
  2689.  
  2690. ΓòÉΓòÉΓòÉ 5.1.4. Direct Frame-Buffer Access ΓòÉΓòÉΓòÉ
  2691.  
  2692. As mentioned earlier, *ppFrameBuffer returned by DiveOpen gives direct 
  2693. addressability to the frame buffer.  In order to write directly to the frame 
  2694. buffer, the DIVE application must perform its own clipping, color conversion, 
  2695. and bank switching. The following functions are provided for direct-frame 
  2696. buffer access: 
  2697.  
  2698.      DiveAcquireFrameBuffer 
  2699.      DiveDeacquireFrameBuffer 
  2700.      DiveSwitchBank 
  2701.      DiveCalcFrameBufferAddress 
  2702.  
  2703.  The DiveQueryCaps function returns whether the display subsystem is 
  2704.  bank-switched. DIVE provides another function called 
  2705.  DiveCalcFrameBufferAddress to get to a location in the frame buffer that 
  2706.  corresponds to a rectangle in desktop  coordinates: 
  2707.  
  2708.       PRECTL prectlDest;           /* Image rectangle in desktop coors  */
  2709.       PVOID pDestinationAddress;   /* Frame buffer address - output     */
  2710.       PULONG pulBankNumber;        /* Display h/w bank number - output  */
  2711.       PULONG pulRemlinesInBank;    /* Lines left in bank - output       */
  2712.  
  2713.       ulErrorCode = DiveCalcFrameBufferAddress(
  2714.               hDiveInst, &prectlDest, &pDestinationAddress,
  2715.               &pulBankNumber, &pulRemlinesInBank);
  2716.  
  2717.  To accomplish correct clipping, prectlDest must be in the application window's 
  2718.  visible region.  If the display hardware is bank-switched, then the 
  2719.  application must not write more than pulRemlinesInBank lines of output before 
  2720.  switching banks.  The data written to pDestinationAddress must be in the 
  2721.  color-encoding scheme of the screen (also provided by DiveQueryCaps).  (Of 
  2722.  course, DIVE can be used to convert to the correct screen color-encoding prior 
  2723.  to writing to the frame buffer by doing a DiveBlitImage to a destination 
  2724.  buffer with the same color-encoding.)  Additionally, if the screen supports 
  2725.  only 256 colors, the data must match the current physical palette. 
  2726.  
  2727.  All write access to the frame buffer must be bracketed by calls to 
  2728.  DiveAcquireFrameBuffer and DiveDeacquireFrameBuffer.  Also, the application 
  2729.  must not attempt to access the frame buffer between receipt of a 
  2730.  WM_VRNDISABLED message and a WM_VRNENABLED message. 
  2731.  
  2732.  This method works only on even bank breaks; indirect access through Dive 
  2733.  BlitImage is recommended on displays with bank breaks that are not aligned on 
  2734.  scan-line boundaries. 
  2735.  
  2736.  In the next example, the application spins off a separate thread to perform 
  2737.  blitting.  The procedure for this thread contains a nested loop that switches 
  2738.  display banks for each image blitted as long as blitting is needed.  The flag 
  2739.  fFBAccessOK is turned off when ever the application window received 
  2740.  WM_VRNDISABLED and is turned on whenever WM_VRNENABLED is received. 
  2741.  
  2742.  A typical application would do the following: 
  2743.  
  2744.   BOOL  fKeepBlitting = TRUE;
  2745.   BOOL  fFBAccessOK;
  2746.   RECTL rectlOutput;           /* Image rectangle in desktop coors  */
  2747.   RECTL rectlDest;             /* Portion to blit in this bank      */
  2748.   ULONG ulMoreLines;           /* Lines in image left to blit       */
  2749.   LONG  lBlitTop;              /* Top of next blit                  */
  2750.   PVOID pDestinationAddress;   /* Frame buffer address - output     */
  2751.   ULONG ulBankNumber;          /* Display h/w bank number - output  */
  2752.   ULONG ulRemlinesInAperature; /* Lines left in bank - output       */
  2753.   BOOL  fAcquired = FALSE;     /* Acquired frame buffer yet         */
  2754.  
  2755.   while (fKeepBlitting)
  2756.     {
  2757.     /* ... Call DiveSetupBlitter as before ...    */
  2758.  
  2759.     /********************************************************/
  2760.     /* Calculate total number of lines to blit.  Then blit  */
  2761.     /* only those lines that will fit in the current bank.  */
  2762.     /* Switch to successive banks until the entire image is */
  2763.     /* blitted.                                             */
  2764.     /********************************************************/
  2765.     ulMoreLines = rectlDest.yTop - rectlDest.yBottom;
  2766.     memcpy( &rectlDest, &rectlOutput, sizeof(RECTL));
  2767.     while (ulMoreLines && fFBAccessOK)
  2768.       {
  2769.       ulErrorCode = DiveCalcFrameBufferAddress(
  2770.           hDive, rectlDest, &pDestinationAddress,
  2771.           &ulBankNumber, &ulRemlinesInAperture);
  2772.       if (!fAcquired)
  2773.         if (!DiveAcquireFrameBuffer( hDive, ulBankNumber))
  2774.           fAcquired = TRUE;
  2775.         else break;
  2776.       DiveSwitchBank( hDive, ulBankNumber);
  2777.         {
  2778.         /* ... write data for (ulRemlinesInAperture) top lines of */
  2779.         /* rectlDest to pDestinationAddress ...   */
  2780.         if (ulRemlinesInAperture < ulMoreLines)
  2781.           {               /* if need next bank    */
  2782.           rectlDest.yTop -= ulRemlinesInAperture;
  2783.           ulMoreLines -= ulRemlinesInAperture;
  2784.           }
  2785.         else ulMoreLines = 0;
  2786.         }
  2787.       if (fAcquired)
  2788.         DiveDeacquireFrameBuffer( hDive);
  2789.           }           /* end: while more lines to blit */
  2790.         }             /* end: blitter loop    */
  2791.  
  2792.  
  2793. ΓòÉΓòÉΓòÉ 5.1.5. DIVE Enhancements ΓòÉΓòÉΓòÉ
  2794.  
  2795. Enhancements made to the DIVE.DLL enable its communication with the 
  2796. GAMESRVR.DLL, providing applications with DIVE functionality.  In addition, the 
  2797. following enhancements have been made to the new DIVE.DLL: 
  2798.  
  2799.      Support for YUV 4-2-2 image format as a source and destination format in 
  2800.       blitting operations. 
  2801.  
  2802.      YUV - LUT8 color conversion improvements. 
  2803.  
  2804.      Capability for 180-degree rotation of output screen image. 
  2805.  
  2806.      Transparent blitting by way of the following new function: 
  2807.  
  2808.             ULONG APIENTRY DiveSetTransparentBlitMode ( HDIVE hDiveInst,
  2809.                                                         ULONG ulTransBlitMode,
  2810.                                                         ULONG ulValue1,
  2811.                                                         ULONG ulValue2 );
  2812.  
  2813.       This function enables transparent blitting using a chroma-key color or 
  2814.       chroma-keying on a color space range. DiveSetTransparentBlitMode must be 
  2815.       called before calling DiveSetBlitter. 
  2816.  
  2817.       hDiveInst (HDIVE) - input 
  2818.                 Display engine DIVE instance. 
  2819.  
  2820.       ulTransBlitMode (ULONG) - input 
  2821.                 Specifies the mode for transparent blitting. Set 
  2822.                 ulTransBlitMode to one of the following values: 
  2823.  
  2824.                 DIVE_TBM_NONE 
  2825.                         No transparency; that is, all pixels are transferred. 
  2826.                         This is the default. 
  2827.  
  2828.                 DIVE_TBM_EXCLUDE_SOURCE_VALUE 
  2829.                         Source pixels with values that exactly match the value 
  2830.                         specified in ulValue1 are not transferred by 
  2831.                         DiveBlitImage. 
  2832.  
  2833.                 DIVE_TBM_EXCLUDE_SOURCE_RGB_RANGE 
  2834.                         Source pixels with values that are within the range 
  2835.                         specified in the RGB color space defined by ulValue1 
  2836.                         (minimum) and ulValue2 (maximum) are not transferred by 
  2837.                         DiveBlitImage. 
  2838.  
  2839.                 DIVE_TBM_INCLUDE_SOURCE_RGB_RANGE 
  2840.                         Source pixels with values that are outside the range 
  2841.                         specified in the RGB color space defined by ulValue1 
  2842.                         (minimum) and ulValue2 (maximum) are not transferred by 
  2843.                         DiveBlitImage. 
  2844.  
  2845.                 DIVE_TBM_EXCLUDE_SOURCE_YUV_RANGE 
  2846.                         Source pixels with values that are outside the range 
  2847.                         specified in the YUV color space defined by ulValue1 
  2848.                         (minimum) and ulValue2 (maximum) are not transferred by 
  2849.                         DiveBlitImage. 
  2850.  
  2851.                 DIVE_TBM_INCLUDE_SOURCE_YUV_RANGE 
  2852.                         Source pixels with values that are outside the range 
  2853.                         specified in the YUV color space defined by ulValue1 
  2854.                         (minimum) and ulValue2 (maximum) are not transferred by 
  2855.                         DiveBlitImage. 
  2856.  
  2857.       ulValue1 (ULONG) - input 
  2858.                 Minimum value in range. 
  2859.  
  2860.       ulValue2 (ULONG) - input 
  2861.                 Maximum value in range. 
  2862.  
  2863.       rc (ULONG) - return 
  2864.                 Return codes indicating success or type of failure: 
  2865.  
  2866.                 DIVE_SUCCESS 
  2867.                         If the function succeeds, 0 is returned. 
  2868.  
  2869.                 DIVE_ERR_INVALID_INSTANCE 
  2870.                         The DIVE instance handle specified in the hDiveInst 
  2871.                         parameter is invalid. 
  2872.  
  2873.       Remarks 
  2874.  
  2875.       The transparent blitting function is based on source pixel values. A 
  2876.       pixel in the destination image buffer is not modified if the 
  2877.       corresponding pixel in the source buffer is "transparent". The 
  2878.       interpretation of the color values specified in ulValue1 and ulValue2 is 
  2879.       dependent on the source image color format (fccSrcColorFormat field in 
  2880.       the SETUP_BLITTER structure) and the transparent blitting mode. 
  2881.  
  2882.       The following table describes the color and range specification: 
  2883.  
  2884.             ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  2885.             ΓöéFOURCC_LUT8                                  ΓöéThe color value is specified in theΓöé
  2886.             Γöé                                             Γöélow 8 bits of the parameter.       Γöé
  2887.             Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2888.             ΓöéFOURCC_Y888, FOURCC_Y2X2, FOURCC_Y4X4,       Γöé23:8 - Y, 15:8 - U, 7:8 - V (bits  Γöé
  2889.             ΓöéFOURCC_YUV9, FOURCC_Y644, FOURCC_Y422        Γöé31:8 ignored)                      Γöé
  2890.             Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  2891.             ΓöéFOURCC_R565, FOURCC_R555, FOURCC_R664,       Γöé23:8 - R, 15:8 - G, 7:8 - B (bits  Γöé
  2892.             ΓöéFOURCC_RGB3, FOURCC_BGR3, FOURCC_RGB4,       Γöé31:8 ignored).  R, G, and B        Γöé
  2893.             ΓöéFOURCC_BGR4                                  Γöécomponents are specified with 8-bitΓöé
  2894.             Γöé                                             Γöésignificance regardless of         Γöé
  2895.             Γöé                                             Γöésignificance in source data.       Γöé
  2896.             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  2897.  
  2898.       Transparent blitting of other source image formats is not supported. 
  2899.  
  2900.       For range comparisons in RGB or YUV, the three components are compared 
  2901.       independently against the minimum and maximum values specified by the 
  2902.       ulValue1 and ulValue2 parameters, respectively. A value is considered to 
  2903.       be within the specified range if it is greater to or equal to ulValue1 
  2904.       and less than or equal to ulValue2. 
  2905.  
  2906.       In DIVE_TBM_EXCLUDE_SOURCE_VALUE transparent blitting mode, the specified 
  2907.       value in ulValue1 is assumed to be in the source color space as described 
  2908.       in the preceding table. For range comparisons, the values specified in 
  2909.       ulValue1 and ulValue2 are assumed to be in the color space in which the 
  2910.       range comparison is to be performed, either YUV or RGB. 
  2911.  
  2912.       With LUT8 source format, in DIVE_TBM_EXCLUDE_SOURCE_VALUE transparent 
  2913.       blitting mode, the value is assumed to be the original LUT8 value. For 
  2914.       other transparent blitting modes (RGB or YUV range), an LUT8 value is 
  2915.       converted to a direct color value based on the current source palette to 
  2916.       determine whether or not it is within the specified range. 
  2917.  
  2918.  
  2919. ΓòÉΓòÉΓòÉ 5.2. Direct Access to Video Buffers ΓòÉΓòÉΓòÉ
  2920.  
  2921. Although DIVE functions are preferred if you are writing applications, for 
  2922. display drivers, you can write directly to video memory, even when running in a 
  2923. Presentation Manager window, by using the enhanced DIVE (EnDIVE) architecture. 
  2924. EnDIVE supports the use of motion video accelerator hardware, providing 
  2925. additional functions for querying information about the color formats supported 
  2926. by the hardware, video memory management and image processing.  See the OS/2 
  2927. Presentation Device Driver Reference for more detailed information about 
  2928. EnDIVE. 
  2929.  
  2930. While this capability provides excellent performance, there are complexities 
  2931. that must be dealt with when using it.  Applications that write directly to the 
  2932. video buffer must provide their own clipping support, color space conversion to 
  2933. the frame buffer, and scaling (if applicable).  Also, on displays that are 
  2934. bank-switched, these applications must invoke functions whenever access moves 
  2935. from one bank to another. 
  2936.  
  2937.  
  2938. ΓòÉΓòÉΓòÉ 5.3. PM Programs in Full Screen ΓòÉΓòÉΓòÉ
  2939.  
  2940. With our new Entertainment Tools, we're including full-screen support built on 
  2941. our DIVE technology.  The latest version of the DIVE interface has been 
  2942. enhanced to allow an application to take over the display and change the 
  2943. display resolution. 
  2944.  
  2945. The GAMESRVR (.DLL) gives full-screen DIVE support to games in video modes 
  2946. other than that used by the OS/2 desktop.  By using the functions provided by 
  2947. the GAMESRVR, PM programs can be written to use the entire screen without 
  2948. paying the penalty of a large frame buffer. 
  2949.  
  2950. Most games on the market today use the 320x200x256 VGA mode.  There are a 
  2951. number of reasons for using this mode that outweigh the mediocre resolution of 
  2952. 320x200 pels in 256 colors.  This mode exists on all VGA and SuperVGA cards. 
  2953. It is easy to use because it uses a flat frame buffer and exactly one byte per 
  2954. pel.  This greatly reduces the complexity of the graphics algorithms and 
  2955. increases their speed. 
  2956.  
  2957. Finally, the size of the buffer is only 64000 bytes.  Compare this to a typical 
  2958. desktop resolution of 1024x768x256 with a frame buffer of 786432 bytes. 
  2959. Because the buffer is 12 times smaller, full-screen operations are 12 times 
  2960. faster. 
  2961.  
  2962.  
  2963. ΓòÉΓòÉΓòÉ 5.3.1. GAMESRVR Installation ΓòÉΓòÉΓòÉ
  2964.  
  2965. The purpose of the GAMESRVR is to support games in video modes other than that 
  2966. used by the OS/2 desktop.  The reason for this is quite simple:  speed. 
  2967.  
  2968. To install the GAMESRVR, run GSRVINST.EXE to perform the following steps: 
  2969.  
  2970.    1. Copy GAMESRVR.DLL and DIVE.DLL to d\OS2\DLL, where d is the boot drive. 
  2971.  
  2972.    2. Add the GAMESRVR key to the PM_ED_HOOKS application in OS2.INI with the 
  2973.       key value of d:\OS2\DLL\GAMESRVR.DLL, where d is the boot drive. 
  2974.  
  2975.    3. If SVGADATA.PMI exists in the d:\OS2 directory, copy SVGA.EXE to d:\OS2, 
  2976.       then execute SVGA ON INIT to rebuild the SVGADATA.PMI file, adding the 
  2977.       320x200x256 mode. 
  2978.  
  2979.    4. Depending on the video card that you have installed, the installation 
  2980.       might end in the full-screen DOS session where SVGA.EXE was executed.  If 
  2981.       so, to return to your OS/2 session, you should type: 
  2982.  
  2983.                 exit
  2984.  
  2985.       The system will have to be rebooted to allow these changes to take 
  2986.       effect.  Applications written to use the GAMESRVR will automatically take 
  2987.       advantage of its presence. 
  2988.  
  2989.  
  2990. ΓòÉΓòÉΓòÉ 5.4. Programming ΓòÉΓòÉΓòÉ
  2991.  
  2992. The GAMESRVR is loaded at execution time by performing a DosLoadModule on 
  2993. GAMESRVR.  If this is successful, the address of the InitGameFrameProc routine 
  2994. my be queried using DosQueryProcAddr.  When you call this routine with the 
  2995. handle of the frame window of the application, it subclasses the frame window 
  2996. procedure.  This allows the GAMESRVR to process all messages sent to the 
  2997. application, especially focus change messages which may require restoration of 
  2998. the original desktop mode. 
  2999.  
  3000. Communication with the GAMESRVR is through the following three messages: 
  3001.  
  3002.  WM_SetVideoMode (0x04A0) 
  3003.     This message uses mp1 to select either one of the preset game window styles 
  3004.     or a specific video mode, as extracted from the table of supported video 
  3005.     modes. 
  3006.  
  3007.     mp1 == 0 
  3008.             Restores the original mode of the desktop, as well as the original 
  3009.             size and location of the application's window. 
  3010.  
  3011.     mp1 == 1 
  3012.             Restores the original mode of the desktop but expands the size of 
  3013.             the client window so that only the client window and the command 
  3014.             bar are visible. 
  3015.  
  3016.     mp1 == 2 
  3017.             Expands the client window to fill the screen.  Then, sets the video 
  3018.             mode to the standard 320x200x256 game mode. 
  3019.  
  3020.     mp1 > 2 
  3021.             Expands the client window to fill the screen.  Then, sets the video 
  3022.             mode defined by the VIDEOMODEINFO structure addressed by mp1. 
  3023.  
  3024.     The return value from this message is 1, if successful, otherwise 0. 
  3025.  
  3026.  WM_NotifyVideoModeChange (0x04A1) 
  3027.     This message is generated by the GAMESRVR to notify the application 
  3028.     immediately before and again immediately after a video mode change. 
  3029.  
  3030.     mp1 == 0 
  3031.             Indicates that the video mode is about to change. 
  3032.  
  3033.     mp1 == 1 
  3034.             Indicates the video mode change is complete. 
  3035.  
  3036.     In both cases, mp2 contains the address of the VIDEOMODEINFO structure, 
  3037.     which describes the video mode of 0 or 1, as described for the 
  3038.     WM_SetVideoMode message.  The value of 2 will never be returned.  Instead, 
  3039.     it is transformed into a pointer to a VIDEOMODEINFO structure. 
  3040.  
  3041.     The return value of this message is ignored. 
  3042.  
  3043.  WM_GetVideoModeTable (0x04A2) 
  3044.     This message is used only if you wish to select a video mode other than the 
  3045.     standard 320x200x256 mode. 
  3046.  
  3047.     mp1        Indicates the address of a PVOID to receive the address of an 
  3048.                array of VIDEOMODEINFO structures describing all of the modes 
  3049.                supported by the current display card.  This array is allocated 
  3050.                for you.  You can delete it yourself or allow it to be 
  3051.                automatically deleted at process termination. 
  3052.  
  3053.     mp2        Indicates the address of a ULONG to receive the number of 
  3054.                structures in the array that was allocated. 
  3055.  
  3056.     The return value from this message is 1 if successful, otherwise 0. 
  3057.  
  3058.  
  3059. ΓòÉΓòÉΓòÉ 5.5. Full-Screen DIVE - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  3060.  
  3061. FSDIVE, the full-screen DIVE programming tutorial (sample), demonstrates the 
  3062. use of multimedia's Direct Interface Video Extensions (DIVE) by repeatedly 
  3063. displaying a short animation sequence of up to 16 bitmaps in a PM window. 
  3064.  
  3065. If other bitmaps than those provided with the sample, the names of the bitmap 
  3066. files must be specified by passing the file names as command line parameters. 
  3067. Also, the bitmaps must be of the same size and color depth.  Only OS/2 .BMP 
  3068. files are recognized and can include 8-, 16-, and 24-bit color bitmaps. 
  3069.  
  3070. Full-Screen mode is activated by using the ALT+Home hot key.  The Home key must 
  3071. be the one on the keypad.  Use ALT+Home to return to the desktop. 
  3072.  
  3073. This programming tutorial is located in 
  3074. TOOLKIT\BETA\SAMPLES\ENTOOLKT\VIDEO\FSDIVE. 
  3075.  
  3076. You can start the programming tutorial by typing the programming tutorial name 
  3077. (FSDIVE.EXE) at the OS/2 command line: 
  3078.  
  3079.    fsdive
  3080.  
  3081. Or by double-clicking on the Full-Screen DIVE icon. 
  3082.  
  3083. Hardware Requirements: 
  3084.  
  3085.      Computer capable of running OS/2 Warp 
  3086.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  3087.  
  3088.  Software Requirements: 
  3089.  
  3090.      DIVE.DLL 
  3091.      OS/2 Warp 3.0 or higher 
  3092.      OS/2 Warp Developer's Toolkit 3.0 or higher 
  3093.      Multimedia support 
  3094.      Software motion video 
  3095.  
  3096.  The maximum window size of this sample has been limited to 640x480 because 
  3097.  larger window size may cause excessive swapping on machines with less than 
  3098.  16MB. 
  3099.  
  3100.  The DIVE sample that comes with this release of The Developer Connection for 
  3101.  OS/2, Volume 8, will not work with the original DIVE.DLL file,  For this 
  3102.  release of the Warp Toolkit, an updated .DLL file is shipped with the sample. 
  3103.  A .DLL with equivalent function will be included in a future version of OS/2 
  3104.  Warp. 
  3105.  
  3106.  The sample is also discussed in Using Your Toolkit under the "What's New" 
  3107.  section. 
  3108.  
  3109.  
  3110. ΓòÉΓòÉΓòÉ 6. 3D Graphics ΓòÉΓòÉΓòÉ
  3111.  
  3112. Imagine a space ship rotating through space, a fighter plane plummeting through 
  3113. the sky after taking a direct hit from its enemy, or any other number of 
  3114. similar scenarios-all of which could be made possible by a new OS/2 3D graphics 
  3115. modeling and rendering API.  3D is the place to be! 
  3116.  
  3117. IBM is bringing you the BRender(TM) Power Rendering System, a real-time, 3D 
  3118. graphics software by Argonaut Technologies Ltd.  IBM is distributing Argonaut's 
  3119. 3D graphics API, known as BRender(TM), in our Entertainment Tools.  The BRender 
  3120. technology is distributed under Argonaut's end-user license.  This version, 
  3121. included with the toolkit, is a limited license permitting the user to evaluate 
  3122. the product.  Should you wish to include BRender technology in your game, you 
  3123. need to contact Argonaut for a commercial license. 
  3124.  
  3125. The BRender Technical Reference manual, is included in addition to other 
  3126. games-related documentation in this Beta.  It can be found in the 
  3127. \TOOLKIT\BETA\BOOK subdirectory. 
  3128.  
  3129. For those of you not already familiar with Argonaut, they are the creators of 
  3130. Nintendo's StarFox and are also the designers of the SuperFX chip, one of the 
  3131. best selling RISC graphics chip in the world.  The BRender technology provides 
  3132. the solution for the speed, size, scalability, flexibility, and power 
  3133. requirements of the most demanding 3D designers. 
  3134.  
  3135. Speed 
  3136. Additional hardware is becoming available from VGA chip companies (such as the 
  3137. Cirrus 3D/VGA chip) for further acceleration.  The BRender Power Rendering 
  3138. System makes true hardware acceleration possible because it was designed with 
  3139. this significant hardware acceleration in mind.  Titles created using the 
  3140. BRender software alone run astoundingly fast and, when hardware acceleration is 
  3141. added, the result is lightning-fast speed.  The benchmarks when running 
  3142. real-world games verify the speed is unmatched by other 3D rendering software. 
  3143.  
  3144. Size 
  3145. Size for running this software is just over 100K, making it the smallest 3D 
  3146. rendering around.  Memory requirements are slashed because of the scanline 
  3147. rendering technique it employs. 
  3148.  
  3149. Scalability 
  3150. The BRender scalable design automatically detects the presence of hardware 
  3151. accelerators to seamlessly exploit available features.  The BRender Power 
  3152. Rendering System runs on 386, 486, Pentium, MacIntosh, and game  machines.  It 
  3153. uses fixed and floating point math.  It offers 16- and 32-bit Z-buffering and 
  3154. other true 3D features such as perspective texture mapping, and object 
  3155. interpenetration.  It also supports almost all resolutions and popular color 
  3156. depths. 
  3157.  
  3158. Created for personal computer and games platforms, the advanced BRender 
  3159. technology provides real-time workstation-class performance on low-end PC and 
  3160. game hardware.  It runs on numerous desktop and games platforms and ports 
  3161. effortlessly to new environments. 
  3162.  
  3163. Flexibility 
  3164. Contained within the BRender Power Rendering System is it's own software 
  3165. rendering 3D graphics library, a definite asset if you are considering porting 
  3166. games across multiple platforms. 
  3167.  
  3168. Power Requirements 
  3169. To be able to achieve DOS-like, high-speed graphics, the BRender technology 
  3170. uses a hierarchical object model for accelerated 3D development.  In addition, 
  3171. it provides comprehensive 3D functionality, automatic object collision 
  3172. detection, and flexible call-back capability. 
  3173.  
  3174.  
  3175. ΓòÉΓòÉΓòÉ 6.1. ROBOT - Programming Tutorial Code ΓòÉΓòÉΓòÉ
  3176.  
  3177. IMPORTANT:  You must read the Argonaut licensing agreement (ARGONAUT.LIC) file 
  3178. and the BRender trademark information file (BRENDER.TMK) before using the 
  3179. BRender Power Rendering System technology provided with this BETA. 
  3180.  
  3181. IBM is providing support for 3D graphics modeling and rendering. This support 
  3182. is independent of the way the data is drawn to the screen. Like the OS/2 
  3183. multimedia implementation of software motion video, this new 3D graphics 
  3184. support can use the DIVE interface for maximum performance. However, GPI or 
  3185. some other custom method can also be used to display to the screen. 
  3186.  
  3187. ROBOT, the programming tutorial (sample), demonstrates how to use the new OS/2 
  3188. version of the Argonaut BRender(TM) technology for real-time, three-dimensional 
  3189. (3D) manipulation of actors.  An actor can be the actual object model, a 
  3190. camera, or a light. 
  3191.  
  3192. There are two parts to this programming tutorial: 
  3193.  
  3194.      The use of BRender technology to perform the 3D manipulations 
  3195.  
  3196.      The use of full-screen DIVE to allocate and display the image buffer and 
  3197.       to do any palette manipulations. 
  3198.  
  3199.  This sample demonstrates a robot walking. The mouse can be used to zoom in and 
  3200.  out and also to rotate the robot in 3D space. 
  3201.  
  3202.  This programming tutorial is located in TOOLKIT\BETA\BRENDER\SAMPLES\ROBOT. 
  3203.  
  3204.  The sample is also discussed in see Using Your Toolkit under the "What's New" 
  3205.  section. 
  3206.  
  3207.  You can start the programming tutorial by typing the programming tutorial name 
  3208.  (ROBOT.EXE) at the OS/2 command line: 
  3209.  
  3210.      robot
  3211.  
  3212.  Or by double-clicking on the Robot icon. 
  3213.  
  3214.  Hardware Requirements: 
  3215.  
  3216.      Computer capable of running OS/2 Warp 
  3217.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  3218.  
  3219.  Software Requirements: 
  3220.  
  3221.      DIVE.DLL 
  3222.      OS/2 Warp 3.0 or higher 
  3223.      OS/2 Warp Developer's Toolkit 3.0 or higher 
  3224.      Multimedia support 
  3225.