
'///////////////////////////////////////////////////////////////////////////////
'//
'// Project Name : IPicture COM Demo for RapidQ
'// Version      : 2.04.2006.21
'// Author       : Don67geo@Yahoo.com
'// Date         : April 21st, 2006
'// Remarks      : For all Windows version
'//
'///////////////////////////////////////////////////////////////////////////////


THE COM PROGRAMMING IN RAPID-Q
==============================
This is the 1st example of using COM with Type Library in Rapid-Q. I just 
discover them recently when I'm revisit 2003 Jacques Phillipe's RQAsm. Finally,
I was able to make the MCALLasm routine which is solved COM interface call in
Rapid-Q. Using Virtual Table offset, it is possible for Rapid-Q to use COM 
Interfaces which is available for Windows OS since ages ago (Win31?). 

Actually, this technique is suppose can be done in 2003 when Jacques release 
his first RQAsm. Or event earlier as 2002 when Pavel "EvilOne" Minayev introduce 
the Assembly CRC32 example. But, it's only 3 year later I've discovered it. 
It's better than nothing at all. Me and Johnk has cracked our head in the past 
to make this COM things working in Rapid-Q. But always go to wrong directions. 

The secret of COM Type Library is offset to Method from it's interface. I've
modified call in MCALL by swapping  3rd and 4th parameters so it can call the
correct address of each method. All you have to do is call a FUNCTIONI that
named COMCall() with the same way how it was written for other compiler. E.g.


   deflng ppDD 'interface for DDraw
   deflng isFail=0

   'Then DDraw API fill ppDD with IDirectDraw interface pointer
   
   isFail=DirectDrawCreate(0,varptr(ppDD),0)

   IF isFail THEN EXIT SUB/FUNCTION/APPLICATION


   'This is how it's look like calling IDirectDraw_Release
   COMCall(8,ppDD)

   'for method with arguments
   COMCall(84,ppDD,640,480,8) 'IDirectDraw_SetDisplayMode



You could simplify them so it can be more user-friendly by using constant
to help you remember the VTBL offset for each method in a COM Interface:

   CONST IDDraw_SetDisplayMode = 84
   CONST IDDraw_SetCooperativeLevel = 80


 'example using constants:

   deflng ppDD 'interface for DDraw
   defint COMRet

   DirectDrawCreate(0,varptr(ppDD),0)

   'With error checker
   COMRet=COMCall(IDDraw_SetCooperativeLevel,ppDD,_
                  hWnd,DDSCL_EXCLUSIVE or DDSCL_FULLSCREEN)

   IF COMRet THEN EXIT SUB/FUNCTION/APP

   'without error checker
   COMCall(IDDraw_SetDisplayMode,ppDD,640,480,8)


Or using the same name but using custom SUB or FUNCTION such as:

    FUNCTION IDDraw_SetCooperativeLevel (ppvObj as long, _
                                         hWnd as long, dwFlag as long)
        Result = COMCall(80,ppvObj,hWnd,dwFlags)
    END FUNCTION


  'uses:

    COMRet = IDDraw_SetCooperativeLevel(ppDD,hWnd, _
                               DDSCL_EXCLUSIVE or DDSCL_FULLSCREEN)

  'for direct call:

    IDDraw_SetDisplayMode(ppDD,640,480,8)


I hope I can explain much more better than this. But, at the moment, it's
only for anyone who can understand it and if you learn from my source code, 
it will make sense to you sooner or later.



THE IPicture Demo Example
=========================
So, don't hold your breath.This is only the first encounter using COM outside
of OLE object and with WIN32 API in Rapid-Q. May be, with this IPicture example 
source code, you could open any type of image file that MicroSoft software that 
capable to open. It give you a capability to render the image to any Device
Context (DC) such as QForm, QImage, QBitmap, QCanvas, QDXScreen and others QGUI.

Check the demo source code for the Image file that supported by the IPicture.
If you interested with a custom object for IPicture in Rapid-Q, you could get
the source code at my personal forum. It still Beta version but it's working as
expected. It just the documentation still in-complete. Here the link:


    http://phpbb-host.com/phpbb/viewtopic.php?t=114&mforum=dobasic


Didn't I've said you didn't need an external dependencies to open GIF or JPG in
your Rapid-Q application? :-D

Below is the complete Internal VTable references for the IPicture:

============================================================================
m_id MethodName                    Parameters
----------------------------------------------------------------------------
  0 IPicture_QueryInterface        lplpvObj& refer IUnknown Interface
  4 IPicture_AddReff               lplpvObj& refer IUnknown Interface
  8 IPicture_Release               lplpvObj& refer IUnknown Interface
 12 IPicture_getHandle             lplpvObj&
 16 IPicture_gethPal               lplpvObj&
 20 IPicture_getType               lplpvObj&
 24 IPicture_getWidth              lplpvObj&
 28 IPicture_getHeight             lplpvObj&
 32 IPicture_Render                lplpvObj&, wDC&, x&, y&, cx&, cy&, xSrc&, ySrc&, cxSrc&, cySrc&, pRcWBounds&
 36 IPicture_sethPal               lplpvObj&, hPal&
 40 IPicture_getCurDC              lplpvObj&
 44 IPicture_SelectPicture         lplpvObj&, hDCIn&, phDCOut&, phBmpOut&
 48 IPicture_getKeepOriginalFormat lplpvObj&
 52 IPicture_setKeepOriginalFormat lplpvObj&, keep&
 56 IPicture_PictureChanged        lplpvObj&
 60 IPicture_SaveAsStream          lplpvObj&, pStream&, fSaveMemCopy$, pCbSize&
 64 IPicture_getAttributes         lplpvObj&

For a detail explanation about IPicture, refer Win32.hlp from MicroSoft.


CREDITS
=======

    JohnK            - The driving force of Rapid-Q users that keep the 
                       interest of graphics programming in RapidQ always high.
            
    Jacques Phillipe - RQAsm King! Thanks for your generous contributions in
                       assembly for Rapid-Q. Hope we could have inline asm in
                       Rapid-Q in the future.
                       
    Gregg Morisson   - Solving API parameters limitations. Never knew that was
                       even possible before. Thanks again, it's a new education
                       for me.



Have fun with your Rapid-Q coding.

-Don.
