home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / PMDIB1.ZIP / PMDIB.TXT < prev    next >
Text File  |  1992-01-10  |  17KB  |  414 lines
  1.  
  2. PMDIB 1.0: A new D.I.B. Manager
  3.  
  4. PMDIB 1.0 is one of the first image processing software
  5. for developers under OS/2 Presentation Manager
  6. that supports DIB's: Device Independent Bitmaps
  7. created under PM or Windows 3.
  8.  
  9. (c) Midori S.A. November 1991, by skarbat@informat
  10.  
  11.  
  12. INTRODUCTION TO DIB's
  13. The introduction of Device Independent Bitmaps (DIB) was one of the most
  14. significant enhancements to the Microsoft Windows 3 Graphics Device
  15. Interface.  Now they are also supported under OS/2 Presentation Manager by
  16. the use of different programming levels.  One of them is by using PMDIB
  17. 1.0.
  18.  
  19. A DIB is defined with a color table that is not dependent to the color
  20. capabilities of the output device, normally the screen.  In contrast, a
  21. device-specific bitmap, uses only the available colors on the display
  22. device.  What PMDIB 1.0 offers here, is the opportunity to add bitmap
  23. graphics (monochrome or color) to your applications.  You can easily
  24. display DIB file format bitmaps and forget about the color limitations of
  25. your output device.  Of course, the same bitmap will be displayed more
  26. accurately under a 8514/A than on an VGA adapter, but that is work for
  27. PMDIB 1.0.
  28.  
  29. With PMDIB 1.0, you can display up to 4 DIB formats:  Monochrome, 16-color,
  30. 256-color, or full 24-bit RGB bitmaps.  The advantage here is that if you
  31. have a 256-color DIB that you want to display under an VGA adapter, PMDIB
  32. 1.0 will notify Presentation Manager upon this, making the bitmap be
  33. displayed using 16 colors with the most accurate color degradation.
  34.  
  35.  
  36.  
  37. PRODUCT DESCRIPTION:
  38. PMDIB 1.0 allows you to display bitmaps in a PM window without the need to
  39. call a single PM API..  PMDIB 1.0 window is created with a single API call
  40. that allows you to create, refresh, destroy, reposition, as well as modify
  41. bitmap display options with subsequent API calls.
  42.  
  43. You can use PMDIB for your applications as if you controlled the graphic
  44. window dynamically, at the time you most prefer, and with the visual
  45. effects that you most desire.
  46.  
  47. PMDIB uses a verb code and additional data parameters to display a graphic
  48. window with a bitmap in it
  49.  
  50. The supported actions for PMDIB are :
  51.         1.      Load and display a bitmap
  52.         2.      Refresh window contents
  53.         3.      Specify a new bitmap source to display
  54.         4.      Contract / expand window dimensions, according to bitmap
  55.         5.      Specify a new location for the window, with dimensions if
  56.                 desired:
  57.         6.      Modify display options, without the need to use its built
  58.                 in popup menus.
  59.  
  60. PMDIB 1.0 can extract the bitmap information from two sources:
  61.  
  62.         1) By full pathname specification
  63.                 a)      a single file from your floppy or hard disk using
  64.                         the form d:\path\filename.ext
  65.                 b)      a full network path (UNC) using the form
  66.                         \\computer\resource\subdir\filename.ext
  67.  
  68.         2) By passing PMDIB a pointer to a buffer where the hole bitmap
  69.            is coded, including its header.
  70.  
  71. PMDIB 1.0 is a callable DLL routine that is compatible from any OS/2 high
  72. or low-level language, and it is supported under OS/2 1.x and OS/2 2.0.
  73.  
  74.  
  75.  
  76. PMDIB API Invocation  -  C Syntax:
  77.  
  78. USHORT PMDIBDLL (PSZ pszBitmapSource, USHORT usVerb, PRECTL prclRectangle) ;
  79.  
  80.  
  81. PSZ pszBitmapSource - (input)
  82. This parameter takes two forms, depending on the verb code.  When you use
  83. DIB_CREATE or DIB_REFRESH_NEW_BMP, this parameter specifies the path for a
  84. DIB filename.  It can be used under two syntax rules:
  85.  
  86.         d:\path\bitmap.bmp
  87.  
  88. Or you can also use UNC (Universal Network Convention) path to locate a
  89. remote file.  This uses the form:
  90.  
  91.         \\computer\resource\subdirectory\filename.ext
  92.  
  93. When the verb is DIB_CREATE_BYPTR or DIB_REFRESH_NEW_BMP_BYPTR, this
  94. parameter points to a buffer where the hole bitmap is coded, including its
  95. header information (wether OS/2 or Windows 3 version).  The maximum lenght
  96. for this buffer is 64K.
  97.  
  98. USHORT usVerb - (input)
  99. A verb can be one of the following:
  100.  
  101. DIB_CREATE_BMP
  102. Use this verb as the first call to PMDIBDLL().  A new window will be
  103. created, and the bitmap graphic file specified in pszBitmapSource will be
  104. drawn in the window.  Its initial window placement will be in the
  105. lower-left corner of the Presentation Manager desktop and its dimensions
  106. adjusted to the bitmap file, unless you have passed a PRECTL as the third
  107. parameter, in which case the window will be adjusted to those coordinates
  108. and dimensions specified under PRECTL using universal coordinates.
  109.  
  110. DIB_REFRESH
  111. This verb does not use any other parameter.  It will redraw its window
  112. contents.
  113.  
  114. DIB_INVERSE
  115. Inverts the Bitmap colors.  This option is available on monochrome and
  116. color bitmaps.
  117.  
  118. DIB_ACTIVATE
  119. Use this verb to activate PMDIB window, and refresh its graphical contents.
  120. Normally it is used when there are other windows behind PMDIB that break
  121. the graphic bitmap.  This message implies that a graphic redraw be
  122. performed.
  123.  
  124. DIB_REFRESH_NEW_BMP
  125. Use this verb to specify a new bitmap file to show inside the window.  The
  126. new bitmap will be replaced in the window, but its dimensions will be kept
  127. like before, unless you pass a PRECTL as the third parameter, in which case
  128. the window will be adjusted to those coordinates and dimensions specified
  129. under PRECTL using universal coordinates.
  130.  
  131. DIB_WND_BMP_STRETCH
  132. The window dimensions will be stretched to those the bitmap specifies.
  133.  
  134. DIB_BMP_WND_STRETCH_ON
  135. The bitmap will be stretched to the window dimensions.
  136.  
  137. DIB_BMP_WND_STRETCH_OFF
  138. The bitmap will NOT be stretched to the window dimensions.  It will be
  139. shown using its default dimensions.
  140.  
  141. DIB_MINIMIZE
  142. The PMDIBDLL Window will be minimized, and its icon will be showed on PM
  143. icon list.
  144.  
  145. DIB_MAXIMIZE
  146. PMDIBDLL window will get the hole PM screen, putting itself in maximized
  147. mode.
  148.  
  149. DIB_RESTORE
  150. The window is restored to its remembered position coordinates when it is in
  151. minimized or maximized state.
  152.  
  153. DIB_EMPTY_WND
  154. This will clear PMDIBDLL window, making it empty.  The bitmap will be
  155. destroyed, so to redisplay the last bitmap, or whatever other you want, you
  156. must call verb DIB_REFRESH_NEW_BMP or DIB_REFRESH_NEW_BMP_BYPTR.
  157.  
  158. DIB_DESTROY_WND
  159. PMDIBDLL Window will be destroyed and will disappear from PM window and
  160. task manager.  To make it come out again, you must call verb DIB_CREATE_BMP
  161. or DIB_CREATE_BMP_BYPTR.
  162.  
  163. DIB_HIDE_WND
  164. PMDIBDLL window will be made unvisible, but not destroyed.  Use
  165. DIB_SHOW_WND to show it again.
  166.  
  167. DIB_SHOW_WND
  168. Will show PMDIBDLL window when it has been hide using verb DIB_HIDE_WND.
  169.  
  170. DIB_POSITION_RECTL
  171. Pass with this verb, the (RECTL *) structure to specify the new window
  172. placement, in absolute coordinates (those that PM Screen uses).
  173.  
  174. DIB_REPOSITION_INITIAL
  175. Window will be placed in the PM screen lower-left corner, and its
  176. dimensions will be adjusted to the bitmap dimensions, unless you have
  177. passed a PRECTL as the third parameter to DIB_CREATE_BMP, in which case the
  178. window will be adjusted to those coordinates and dimensions specified under
  179. PRECTL using universal coordinates.
  180.  
  181. DIB_ENABLE_POPUPMENU
  182. Mouse second button pops up image control menu.
  183.  
  184. DIB_DISABLE_POPUPMENU
  185. Mouse second button does nothing. popup menu does not exist.
  186.  
  187. DIB_LOCK_UPDATE
  188. This verb prevents a window from updating.  While the window is locked, no
  189. drawing will take place on the screen.  Use DIB_UNLOCK_UPDATE to repaint
  190. the window image contents.
  191.  
  192. DIB_UNLOCK_UPDATE
  193. The window locking that was previously issued using DIB_LOCK_UPDATE verb,
  194. is now unlocked, thus allowing itself to repaint its invalidated window
  195. areas.
  196.  
  197. DIB_CREATE_BMP_BYPTR   (pszBitmapSource points to DIB buffer)
  198. Use this verb as the first call to PMDIBDLL().  A new window will be
  199. created, and the bitmap graphic buffer pointed to by the paramter
  200. pszBitmapSource will be drawn in the window.  Its initial window placement
  201. will be in the lower-left corner of the Presentation Manager desktop and
  202. its dimensions adjusted to the bitmap file, unless you have passed a PRECTL
  203. as the third parameter, in which case the window will be adjusted to those
  204. coordinates and dimensions specified under PRECTL using universal
  205. coordinates.
  206.  
  207. DIB_REFRESH_NEW_BMP_BYPTR   (pszBitmapSource points to DIB buffer)
  208. Use this verb to specify a new bitmap to show inside the window.  The new
  209. bitmap will be replaced in the window, but its dimensions will be kept like
  210. before, unless you pass a PRECTL as the third parameter, in which case the
  211. window will be adjusted to those coordinates and dimensions specified under
  212. PRECTL using universal coordinates.
  213.  
  214. PRECTL prclRectangle - (input)
  215. This is a pointer to a RECTL structure.  You will use this parameter with
  216. the following verb calls only:
  217.  
  218.         DIB_CREATE_BMP
  219.         DIB_REFRESH_NEW_BMP
  220.         DIB_POSITION_RECTL
  221.         DIB_CREATE_BMP_BYPTR   (pszBitmapSource points to DIB buffer)
  222.         DIB_REFRESH_NEW_BMP_BYPTR   (pszBitmapSource points to DIB buffer)
  223.  
  224. Any other verb ignores this parameter, you should supply a NULL pointer,
  225. explicitly.
  226.  
  227. The structure of a RECTL data type is defined as follows.
  228.  
  229.         // Taken from OS2DEF.h (Microsoft C 6.0)
  230.  
  231.         typedef struct _RECTL {
  232.            LONG    xLeft;
  233.            LONG    yBottom;
  234.            LONG    xRight;
  235.            LONG    yTop;
  236.         } RECTL;
  237.  
  238. USHORT rc - (return)
  239. PMDIBDLL Return code list:
  240.  
  241.            DIBERR_BMP_NOTFOUND
  242.            DIBERR_BMP_ERROR_READING
  243.            DIBERR_BMP_BAD_SIGNATURE
  244.            DIBERR_BMP_CORRUPTED
  245.            DIBERR_BMP_ERROR_READ_COLORS
  246.            DIBERR_BMP_LARGER_64K
  247.            DIBERR_PMDIBDLL_EXISTS
  248.            DIBERR_RESOURCES_NOTFOUND
  249.            DIBERR_PMDIBDLL_NOEXISTS
  250.            DIBERR_THREAD_ERROR
  251.            DIBERR_RECTL_ERROR
  252.            DIBERR_RECTL_ERROR
  253.            DIBERR_VERB_UNKNOWN
  254.            DIBERR_OK
  255.  
  256.  
  257.  
  258.  
  259.  
  260. PMDIB API Invocation  -  COBOL Syntax:
  261.  
  262. As to be able to support the verb codes as constant strings in your program
  263. instead of USHORT values, you should include in your Cobol main program,
  264. the file PMDIB.CPY at the beginning of your source, like this:
  265.  
  266.       COPY "PMDIB.CPY".
  267.  
  268. Parameter variables under Cobol should be defined as follows:
  269.  
  270.       01 PARAMETERS.
  271.           05 RECTANGLE-POINTER           PIC 9(9) COMP-5 VALUE 0.
  272.           05 USVERB                      PIC 9(4) COMP-5.
  273.           05 IMAGE-POINTER               USAGE IS POINTER.
  274.  
  275. Parameters to DLL under cobol are coded last to first, so the API call to
  276. PMDIB 1.0 should be coded like this:
  277.  
  278.       CALL "PMDIBDLL" USING      BY VALUE RECTANGLE-POINTER,
  279.                                  BY VALUE USVERB,
  280.                                  BY REFERENCE IMAGE-POINTER.
  281.  
  282. In this example, the verb DIB-CREATE-BMP-BYPTR is used.  Before this call,
  283. you should move the Bitmap information into this buffer, an then pass the
  284. address to the first item of this buffer to PMDIBDLL().
  285.  
  286. Note that the RC value will be placed in RETURN-CODE internal Cobol
  287. variable.  You should test the return code using the formula below:
  288.  
  289.        IF RETURN-CODE NOT EQUAL DIBERR-OK
  290.      *       Process error here
  291.        ELSE
  292.      *       API call has been successfull
  293.        ENDIF.
  294.  
  295. The values in Cobol for the PMDIB action verb codes are listed below.  This
  296. is PMDIB.CPY file, actually, the one you include with a COPY Cobol
  297. statement in your source.
  298.  
  299.      *
  300.      * PMDIBDLL COPY FILE FOR COBOL
  301.      *
  302.      * This include file contains the necessary verb codes
  303.      * and error codes for calling PMDIBDLL,
  304.      *
  305.      * (c) Midori S.A. 1991
  306.      * by Skarbat@informat
  307.      *
  308.      *
  309.      * ---------------------------------------------------
  310.      *
  311.      *   Below follows the PMDIBDLL verbs definition
  312.      *
  313.       01 DEFINE.
  314.      *
  315.          05 DIB-CREATE-BMP            PIC 9(9) COMP-5 VALUE 5000.
  316.          05 DIB-REFRESH               PIC 9(9) COMP-5 VALUE 5010.
  317.          05 DIB-INVERSE               PIC 9(9) COMP-5 VALUE 5020.
  318.          05 DIB-ACTIVATE              PIC 9(9) COMP-5 VALUE 5030.
  319.          05 DIB-REFRESH-NEW-BMP       PIC 9(9) COMP-5 VALUE 5040.
  320.          05 DIB-WND-BMP-STRETCH       PIC 9(9) COMP-5 VALUE 5050.
  321.          05 DIB-BMP-WND-STRETCH-ON    PIC 9(9) COMP-5 VALUE 5060.
  322.          05 DIB-BMP-WND-STRETCH-OFF   PIC 9(9) COMP-5 VALUE 5070.
  323.          05 DIB-MINIMIZE              PIC 9(9) COMP-5 VALUE 5080.
  324.          05 DIB-MAXIMIZE              PIC 9(9) COMP-5 VALUE 5090.
  325.          05 DIB-RESTORE               PIC 9(9) COMP-5 VALUE 5100.
  326.          05 DIB-EMPTY-WND             PIC 9(9) COMP-5 VALUE 5110.
  327.          05 DIB-DESTROY-WND           PIC 9(9) COMP-5 VALUE 5120.
  328.          05 DIB-HIDE-WND              PIC 9(9) COMP-5 VALUE 5130.
  329.          05 DIB-SHOW-WND              PIC 9(9) COMP-5 VALUE 5140.
  330.          05 DIB-POSITION-RECTL        PIC 9(9) COMP-5 VALUE 5150.
  331.          05 DIB-REPOSITION-INITIAL    PIC 9(9) COMP-5 VALUE 5160.
  332.          05 DIB-ENABLE-POPUPMENU      PIC 9(9) COMP-5 VALUE 5170.
  333.          05 DIB-DISABLE-POPUPMENU     PIC 9(9) COMP-5 VALUE 5180.
  334.          05 DIB-LOCK-UPDATE           PIC 9(9) COMP-5 VALUE 5190.
  335.          05 DIB-UNLOCK-UPDATE         PIC 9(9) COMP-5 VALUE 5200.
  336.          05 DIB-CREATE-BMP-BYPTR      PIC 9(9) COMP-5 VALUE 5210.
  337.          05 DIB-REFRESH-NEW-BMP-BYPTR PIC 9(9) COMP-5 VALUE 5220.
  338.      *
  339.      *   Below follows the PMDIBDLL return code error constants
  340.      *
  341.       01 DEFINE.
  342.      *
  343.          05 DIBERR-BMP-NOTFOUND          PIC 9(9) COMP-5 VALUE  6010.
  344.          05 DIBERR-BMP-ERROR-READING     PIC 9(9) COMP-5 VALUE  6020.
  345.          05 DIBERR-BMP-BAD-SIGNATURE     PIC 9(9) COMP-5 VALUE  6030.
  346.          05 DIBERR-BMP-CORRUPTED         PIC 9(9) COMP-5 VALUE  6040.
  347.          05 DIBERR-BMP-ERROR-READ-COLORS PIC 9(9) COMP-5 VALUE  6050.
  348.          05 DIBERR-BMP-LARGER-64K        PIC 9(9) COMP-5 VALUE  6060.
  349.          05 DIBERR-PMDIBDLL-EXISTS       PIC 9(9) COMP-5 VALUE  6070.
  350.          05 DIBERR-RESOURCES-NOTFOUND    PIC 9(9) COMP-5 VALUE  6080.
  351.          05 DIBERR-PMDIBDLL-NOEXISTS     PIC 9(9) COMP-5 VALUE  6090.
  352.          05 DIBERR-THREAD-ERROR          PIC 9(9) COMP-5 VALUE  6100.
  353.          05 DIBERR-RECTL-ERROR           PIC 9(9) COMP-5 VALUE  6110.
  354.          05 DIBERR-VERB-UNKNOWN          PIC 9(9) COMP-5 VALUE  6120.
  355.          05 DIBERR-OK                    PIC 9(9) COMP-5 VALUE  8000.
  356.      *
  357.      *   End of copy file.
  358.      *
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366. Statements of Development
  367. In our development politics, we facilitate to our users, minimal cost
  368. upgrades (based on delivery rates) as well as information on new
  369. actualizations as soon as they come out.
  370.  
  371. We offer technical service for any doubt or problem that implies the use or
  372. implantation of our products by telephone contact or through the
  373. cyberspace, by using email, reaching then, all the users of our
  374. applications.
  375.  
  376. In preparation for a new version of PMDIB, the following items are being
  377. used now:
  378.  
  379. 32 bit version of OS/2 2.0 to handle unknown bitmap lenghts.  Manipulation
  380. of advanced DIB formats of OS/2 2.0 and compressed.  Implantation of a
  381. second module that allows the developer to call PMDIB remotely, thus making
  382. it available to develop distributed applications.
  383.  
  384. List Prices
  385.  
  386. Our list prices for PMDIB 1.0 are the following:
  387.                                                Final      Distributors
  388. A copy of PMDIB 1.0, for single use            $110, 65   $90, 49
  389. A copy of PMDIB 1.0, unlimited dev. license    $330, 195  $250, 152
  390.  
  391. Final Notes
  392. MIDORI S.A. is a registered trademark of MIDORI S.A.
  393. PMDIB 1.0  is a registered trademark of MIDORI S.A.
  394. Microsoft C 6.0 is a registered trademark of Microsoft Corp.
  395. Windows 3 is a registered trademark of Microsoft Corp.
  396. OS/2 is a registered trademark of IBM Corp. & Microsoft Corp.
  397.  
  398. This is an evaluation copy of a final version.  It will allow to be
  399. operative in your workstation for certain random time, normally not more
  400. than half an hour.  After it will invisibly disappear from the screen.  You
  401. can start it again, although.
  402.  
  403. If you like this product, and are interested to contact us in some way, do
  404. not hesitate to drop us a line, fax or email.
  405.  
  406. MIDORI S.A.
  407. Calabria, 241 - Entlo. 5ª
  408. Tel: 93-419 12 37
  409. Fax: 93-430 74 08
  410. 08029 Barcelona
  411. Internet: 100021.2114@compuserve.com
  412. CompuServe ID: 100021,2114
  413.  
  414.