What is the .Render method of the stdPicture object and how does one use it.
FYI: a stdPicture object is either an object declared as stdPicture or any VB .Picture/.Image property, including those of forms, image controls, pictureboxes, etc. Some other properties may be stdPicture objects too, like a command button's .DisabledPicture property or a form's .Icon property.
The .Render method has all the benefits of VB's PaintPicture method, except one, and has a few additional benefits that VB's PaintPicture does not. In short, you have some more flexibility with .Render, but its usage is not widely known or understood.
What does PaintPicture do that .Render cannot? It can render a stdPicture object with different raster operations, i.e., vbSrcPaint, vbSrcErase, etc. The .Render method cannot by itself. SetROP2 API can do the job though.
What does .Render do that PaintPicture cannot? A few things
1. It can render to any DC, memory DC, DC returned by API, or VB .hDC property (major advantage)
2. It can render transparent GIFs, maintaining transparency (minor advantage)
3. It is faster because less VB overhead is involved
What APIs do PaintPicture & .Render replicate? BitBlt, StretchBlt, DrawIcon, DrawIconEx and metafile rendering. So you see, you have some powerful API replication in some common VB methods.
Why is .Render not understood well? Because it is harder to use and PaintPicture can suffice a vast majority of the time and is easier to use. To understand .Render, you need to understand a bit about bitmaps and .Render's parameter requirements
a. Destination parameters for .Render are in pixels
b. Source parameters for .Render are in himetrics
c. stdPicture objects are DIBs, stored upside down. So source parameters must be flipped vertically when rendering.
Knowing the above, one can build a custom Render function using a stdPicture object. The following includes options for: stretching, scaling, offsetting, centering, partial rendering, and user-defined scalemodes.
Simply copy & paste to your project. Commented well in the code.
Tip: To make copying easier, hit the "Quote" button below & copy from that window.
vb Code:
Private Function RenderStdPicture(theTarget As Variant, thePic As StdPicture, _
Optional ByVal destX As Single, Optional ByVal destY As Single, _
Optional ByVal destWidth As Single, Optional ByVal destHeight As Single, _
Optional ByVal srcX As Single, Optional ByVal srcY As Single, _
Optional ByVal srcWidth As Single, Optional ByVal srcHeight As Single, _
Optional ByVal ParamScaleMode As ScaleModeConstants = vbUser, _
Optional ByVal Centered As Boolean = False, Optional ByVal ZoomFactor As Single = 1&) As Boolean
' Return Value [out]
' If no errors occur, return value is True. If error or invalid parameters passed, value is False
' Parameters [in]
' theTarget: a VB form, picturebox, usercontrol or a valid hDC (no error checking for valid DC)
' ... If Object, then it must expose a ScaleMode and hDC property
' ... and if centering and an object, must also expose ScaleWidth & ScaleHeight properties
' thePic: a VB ImageControl, stdPicture object, or VB .Picture property
' destX: horizontal offset on theTarget where drawing begins, default is zero
' destY: vertical offset on theTarget where drawing begins, default is zero
' destWidth: rendered image width & will be multiplied against ZoomFactor; default is thePic.Width
' destHeight: rendered image height & will be multiplied against ZoomFactor; default is thePic.Height
' srcX: horizontal offset of thePic to begin rendering from; default is zero
' srcY: vertical offset of thePic to begin rendering from; default is zero
' srcWidth: thePic width that will be rendered; default is thePic.Width
' srcHeight: thePic height that will be rendered; default is thePic.Height
' ParamScaleMode: Scalemode for passed parameters.
' If vbUser, then theTarget scalemode is used if theTarget is an Object else vbPixels if theTarget is an hDC
' Centered: If True, rendered image is centered in theTarget, offset by destX and/or destY
' If theTarget is a DC, then Centered is ignored. You must pass the correct destX,destY values
' ZoomFactor: Scaling option. Values>1 zoom out and Values<1||>0 zoom in
' Tip: To stretch image to a picturebox dimensions, pass destWidth & destHeight
' as the picturebox's scalewidth & scaleheight respectively and ZoomFactor of 1
If thePic Is Nothing Then Exit Function ' sanity checks first
If thePic.Handle = 0& Then Exit Function
If ZoomFactor <= 0! Then Exit Function
Dim Width As Single, Height As Single, destDC As Long
' the stdPicture.Render method requires vbPixels for destination and vbHimetrics for source
Width = ScaleX(thePic.Width, vbHimetric, vbPixels) ' image size in pixels
If Err Then Err.Clear Else RenderStdPicture = True
End If
On Error GoTo 0
End Function
Edited: Short version, no resizing, scaling, positioning, or any other options. Just draw picture at 0,0 coordinates on any DC
Code:
' destDC can be any DC
Dim thePic As stdPicture
Set thePic = LoadPicture("C:\Images\Screenshots\image1002.jpg")
With thePic
.Render (destDC), 0&, 0&, ScaleX(.Width, vbHimetric, vbPixels), ScaleY(.Height, vbHimetric, vbPixels), _
0&, .Height, .Width, -.Height, ByVal 0&
End With
Edited: Pointed out in post #8 below, we should use Single vartypes for our variables we plan on passing to .Render
Last edited by LaVolpe; Dec 28th, 2014 at 11:56 PM.
Reason: updated comments/sample code
Insomnia is just a byproduct of, "It can't be done"
Option Explicit
Dim m_Pic As StdPicture
Private Sub Form_Load()
Set m_Pic = LoadPicture(App.Path & "\Test.gif")
End Sub
Private Sub Form_Paint()
Dim Width As Long, Height As Long
' convert himetric to pixels
Width = Me.ScaleX(m_Pic.Width, vbHimetric, vbPixels)
Height = Me.ScaleY(m_Pic.Height, vbHimetric, vbPixels)
' render normal
m_Pic.Render Me.hDC, 0, 0, --Width, --Height, 0, m_Pic.Height, m_Pic.Width, -m_Pic.Height, ByVal 0&
' render mirrored
m_Pic.Render Me.hDC, --Width, 100, -Width, --Height, 0, m_Pic.Height, m_Pic.Width, -m_Pic.Height, ByVal 0&
End Sub
It seems passing variables is somehow troublesome, I don't really understand why it would give the Type Mismatch error, but using -- is good enough to get rid of it.
Here is a short ready-to-go function and a sample attachment project. This project is especially a sample on how to draw a transparent GIF.
Code:
Private Sub DrawSprite(ByVal TargetDC As Long, Sprite As StdPicture, ByVal X As Long, ByVal Y As Long, Optional ByVal Center As Boolean, Optional ByVal Mirror As Boolean, Optional ByVal Flip As Boolean)
Dim Width As Long, Height As Long
' convert himetric to pixels, manual edition
Width = ((m_Sprite.Width / 2540) * 1440) \ Screen.TwipsPerPixelX
Height = ((m_Sprite.Height / 2540) * 1440) \ Screen.TwipsPerPixelY
' center sprite on X & Y?
If Center Then X = X - Width \ 2: Y = Y - Height \ 2
' need flip or mirror?
If Flip Then Y = Y + Height: Height = -Height
If Mirror Then X = X + Width: Width = -Width
' draw it (the -- trick fixes the Type Mismatch error)
Sprite.Render --TargetDC, --X, --Y, --Width, --Height, _
0, Sprite.Height, Sprite.Width, -Sprite.Height, ByVal 0&
End Sub
I noticed ScaleX & ScaleY throw off the pixel values a bit too much for my taste, it seems doing calculation using \ operator for the final math works faster and gives a bit nicer looking code than forcing rounding up.
For comparison, here is the old Width & Height calculation:
Code:
' convert himetric to pixels (always round up using negative for Int)
Width = -Int(-Me.ScaleX(m_Sprite.Width, vbHimetric, vbPixels))
Height = -Int(-Me.ScaleY(m_Sprite.Height, vbHimetric, vbPixels))
It seems passing variables is somehow troublesome, I don't really understand why it would give the Type Mismatch error, but using -- is good enough to get rid of it.
Any method that forces VB to re-evaluate the variables will work
--Width
Width Or 0&
Width \ 1&
etc, etc
More compact solution? I prefer the Or 0& method. Easier to read, less confusion in my opinion & possibly less cpu cycles (though not interested to prove/disprove it).
This is even more compact and far easier on the eyes:
It isn't any shorter (same amount of characters), but it probably confuses less most people For me the Or 0& is harder to read and it probably takes longer to understand for a random guy than --. But () wins being best for the eyes. -- wins for using least pixels representing a character on the screen!
Too bad it looks like Render is one of those hugely underused functions only because it is a little hard to deal with. Maybe I'll try do a small game without a single graphical API declaration just for the fun of it, some day
Can someone explain WHY it can't take LONG datatype variables directly as input, without any of this funny business? Clearly a number of the parameters are "As Long" (when you type out the function and hit space or comma it shows what it is expecting as input INCLUDING the data types). So why does passing them Long type variables cause this error. This is the ONLY function that has the issue of not accepting the very data type it claims to be expecting. Please explain what is going on here.
Thanks for bringing my attention to this little known method. It really does wonders. It has helped me improve the speed of my double buffering system by a tremendous amount.
Now to clear the bit of confusion about .render, here is the answer to one mitigated point in the above discussion.
1- The MSDN page reference in post #1 is not very complete since it does not document the types for calling the routine and it does not mention either the upside down nature of the stdPicture bit arrangement
2- VB's object browser says this about the .render procedure :
Sub Render(hdc As Long, x As Long, y As Long, cx As Long, cy As Long, xSrc As OLE_XPOS_HIMETRIC, ySrc As OLE_YPOS_HIMETRIC, cxSrc As OLE_XSIZE_HIMETRIC, cySrc As OLE_YSIZE_HIMETRIC, prcWBounds As Any)
This is NOT accurate. The arguments for destination are NOT type Long. Also, OLE_XPOS_HIMETRIC is quite undescriptive for programmers not familiar with Windows Foundation Classes. Furthermore, VB6-API programmers might think the prominent type LONG might do the job, but that would be surprising since the base unit of hiMetric is .01 millimeters.
As it turns out, ALL arguments except for hdc and wbounds are of type SINGLE.
This line of code will call .render with the appropriate variable types and without the infamous type mismatch error :
and that is only logical since .render is designed to work with any units supported by the stdPicture scale mode, and not only typical pixel unit used normally with gdi or gdi+ routines.
No errors & it renders just fine. Notice that the destination position/size are all LONG vartypes
But when passing variables, then the issue arises: This line of code generates the error.
Code:
Dim Xy As Long, Cxy As Long
Cxy = 32
Me.Icon.Render Me.hDC, Xy, Xy, Cxy, Cxy, 0&, Me.Icon.Height, Me.Icon.Width, -Me.Icon.Height, ByVal 0&
But using Singles instead of Longs... no errors
Code:
Dim Xy As Single, Cxy As Single, lDC As Long
Cxy = 32: lDC = Me.hDC
Me.Icon.Render (lDC), Xy, Xy, Cxy, Cxy, Xy, Me.Icon.Height, Me.Icon.Width, -Me.Icon.Height, ByVal 0&
Last edited by LaVolpe; Dec 28th, 2014 at 11:57 PM.
Reason: added a few examples
Insomnia is just a byproduct of, "It can't be done"
Don't know if anyone has noticed but one "major" drawback of using the this .Render Method though is that the picture doesn't persist after a refresh.
For example: Upon activation of the Form, render the picture onto the form's DC ( or any control's Dc) as shown on this thread then carry out a refresh of the form or simply change the form's zoom and you will see that the form's picture disappears.
This drawback is more relevant and limiting in VBA because office userforms don't have a Paint event where this .Render code can conviniently be re-executed to restore the picture after a each refresh.
The ppl don't understand the .RENDER because the help tag (the popup), describes it as long , long, long, long, long , Ole_xpos_himetric, ole_ypos_himetric, ole_xsize_himetric, ole_ysize_himetric, any
and when you try other than 0,0,pic.width,pic.height.... it will return Type mismatch error 13
doesn't matter if you do proper
dim picw as OLE_XSIZE_HIMETRIC .... and so on.
it will return type mismatch any attempt
Because what works, is to use all "Single" variables.
include if you do it (air coding)
.render hdc, , , , , usercontrol.scalex(value, pixels, himetrics) it will fail with error 13.
the only way is to use Single variable, and asign the value singleX = usercontrol.scalex(value, pixels, himetrics) and then use the singleX variable in the .render method.
I ran like 3 hours of headaches about this..., Microsoft ruined it with the help popup.
(when writing code to render partial picture related to the XY scrolling values for the usercontrol)
Last edited by flyguille; Jul 12th, 2019 at 07:15 AM.
I believe the real problem is with the VB stdPicture object somehow, someway.
Look at the two .Render calls below. They are identical with the exception of which interface they are called on. When using IPicture, no issues passing Longs. When using stdPicture (or IPictureDisp or Picture), then we have mismatch errors.
Code:
Dim xy As Long, cxy As Long, tDC As Long
cxy = 64
tDC = Me.hDC
Dim oIPict As IPicture ' << IPicture object
Set oIPict = Me.Icon
With oIPict
.Render tDC, xy, xy, cxy, cxy, 0, .Height, .Width, -.Height, ByVal 0&
End With
With Me.Icon ' << stdPicture, IPictureDisp, Picture object
.Render tDC, xy, xy, cxy, cxy, 0, .Height, .Width, -.Height, ByVal 0&
End With
Insomnia is just a byproduct of, "It can't be done"
I believe the real problem is with the VB stdPicture object somehow, someway.
Look at the two .Render calls below. They are identical with the exception of which interface they are called on. When using IPicture, no issues passing Longs. When using stdPicture (or IPictureDisp or Picture), then we have mismatch errors.
Code:
Dim xy As Long, cxy As Long, tDC As Long
cxy = 64
tDC = Me.hDC
Dim oIPict As IPicture ' << IPicture object
Set oIPict = Me.Icon
With oIPict
.Render tDC, xy, xy, cxy, cxy, 0, .Height, .Width, -.Height, ByVal 0&
End With
With Me.Icon ' << stdPicture, IPictureDisp, Picture object
.Render tDC, xy, xy, cxy, cxy, 0, .Height, .Width, -.Height, ByVal 0&
End With
yup all StdPictures here.... but it runs me nut! Crazy man!.
Include I copied the .render from other Usercontrol that is well known that is working... but in this one I was unable to get it to work. Include I tested if was something with the original JPG image, so get the MSPAINT resaved it (the original was from the web), and nothing.... 3 hours of hazle. !!! The others usercontrols gets images from .PNG files, but IIRC, when loading it in stdpictures, all are converted to bitmaps so the source don't matter, right?
Last edited by flyguille; Jul 12th, 2019 at 04:44 PM.
This sub *always* works w/ whatever arguments you pass in (constants, strings, retvals from ScaleX/Y), because the parameters of pvRenderPicture are effectively local variables (data on stack) for the compiler and so .Render method gets all its actual arguments from local variables of correct data-type e.g. Longs and OLE_X/YPOS_HIMETRICs.
This sub *always* works w/ whatever arguments you pass in (constants, strings, retvals from ScaleX/Y), because the parameters of pvRenderPicture are effectively local variables (data on stack) for the compiler and so .Render method gets all its actual arguments from local variables of correct data-type e.g. Longs and OLE_X/YPOS_HIMETRICs.
cheers,
</wqw>
your code works because you declare it as IPicture, not because you use HIMETRIC data types,
I got the pictures in StdPicture variables, and using the .render with that image, you can't use HIMETRIC data type, it will get error 13.
That is what runs me nut.
Now, your code can be called with an StdPicture, when is declaring to accept IPicture?
if the variables are local, vs globals has nothing to do. It is just that the compiler understand that StdPicture ->,,,, HIMETRIC Type Mismatch..... so StdPicture ,,,,,, Single = ok. and Ipicture,,,,,, Himetric -> ok, Ipicture,,,,,, single -> ????
VB allows to do SET IPicture = StdPicture? without performance loss?
Last edited by flyguille; Jul 13th, 2019 at 12:45 PM.
If you declare varIPic as IPicture then call: Set varIPic = someStdPic, any performance loss would be negligible. Here is what VB is doing, in simple terms:
Code:
Dim varIPic As IPicture >> VB creates new variable
Set varIPic = someStdPicture >> VB performs these steps
Call someStdPicture's IUnknown:QueryInterface to see if it supports IPicture & it will
QueryInterface returns existing IPicture interface and assigns it to varIPic
-- when varIPic is set to Nothing or goes out of scope, VB calls IUnknown:Release on it
So, by using another interface, there are a few extra calls behind the scenes, but those are going to be fast. There might actually be a slight performance boost if stdPicture's Render call uses IDispatch:Invoke or the DispInvoke API and IPicture's Render call does not. Reason is usage of variants.
Edited and just FYI:
OLE_XPOS_HIMETRIC, OLE_YPOS_HIMETRIC, OLE_XSIZE_HIMETRIC, OLE_YSIZE_HIMETRIC can all be substituted with LONGs. This is because, the typelib defines those as aliases/typedefs of the vartype Long. Of course, if passing longs, use IPicture.Render
from the typelib
Code:
typedef [uuid(66504306-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_XPOS_HIMETRIC;
typedef [uuid(66504307-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_YPOS_HIMETRIC;
typedef [uuid(66504308-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_XSIZE_HIMETRIC;
typedef [uuid(66504309-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_YSIZE_HIMETRIC;
Last edited by LaVolpe; Jul 13th, 2019 at 02:04 PM.
Insomnia is just a byproduct of, "It can't be done"
If you declare varIPic as IPicture then call: Set varIPic = someStdPic, any performance loss would be negligible. Here is what VB is doing, in simple terms:
Code:
Dim varIPic As IPicture >> VB creates new variable
Set varIPic = someStdPicture >> VB performs these steps
Call someStdPicture's IUnknown:QueryInterface to see if it supports IPicture & it will
QueryInterface returns existing IPicture interface and assigns it to varIPic
-- when varIPic is set to Nothing or goes out of scope, VB calls IUnknown:Release on it
So, by using another interface, there are a few extra calls behind the scenes, but those are going to be fast. There might actually be a slight performance boost if stdPicture's Render call uses IDispatch:Invoke or the DispInvoke API and IPicture's Render call does not. Reason is usage of variants.
Edited and just FYI:
OLE_XPOS_HIMETRIC, OLE_YPOS_HIMETRIC, OLE_XSIZE_HIMETRIC, OLE_YSIZE_HIMETRIC can all be substituted with LONGs. This is because, the typelib defines those as aliases/typedefs of the vartype Long. Of course, if passing longs, use IPicture.Render
from the typelib
Code:
typedef [uuid(66504306-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_XPOS_HIMETRIC;
typedef [uuid(66504307-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_YPOS_HIMETRIC;
typedef [uuid(66504308-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_XSIZE_HIMETRIC;
typedef [uuid(66504309-BE0F-101A-8BBB-00AA00300CAB), public]
long OLE_YSIZE_HIMETRIC;
Yes, using long works when all stdPictures are loaded from PNGs using the GDI, so, as my skins are all done with png, and I used longs in the .render, never found this problem, but then in another usercontrol object, I use a StdPicture which loads a JPG from web (the jpg is created in PHP api at webserver side), so, download and using the normal LoadPciture() from VB, and first attempt used all longs as always, failes, so, I observed the help tips, used the HIMETRIC types, failes, failes failed....., set up like 0,0,usercontrol.scalex, usercontrol.scaley FAILED.
imagine a student encounter this problem, he will think, the .render is crap, better stay away from that. And so, that must be the "it is not well known", or unpopular.
your code works because you declare it as IPicture, not because you use HIMETRIC data types
You are right about IPicture being the reason everything is working with my code. I never said it's working because it's using "HIMETRIC data types" but the root-cause hypothesis of using local variable is still wrong. My bad here!
The StdPicture class is declared as this is stdole2.tlb
while the dispinterface Picture is further aliased as this
Code:
typedef [public] Picture IPictureDisp;
So StdPicture supports both IPicture and Picture (a.k.a IPictureDisp) interfaces and the second one is its default interface that VB6 uses when not explicitly cast to IPicture.
Both IPicture and IPictureDisp have Render methods
. . . but these two Render methods are implented differently -- one is a vtable entry while the other on the dispinterface is purely late-bound (IDispatch::Invoke) only.
This late-bound one is failing and is 100% buggy because it cannot accept VT_BYREF flagged variants -- it just compares paramCx.vt == VT_I4 and all other integral vartypes and bails out w/ E_PARAMETER if type is too much for it.
When you pass hDC + 0 or -(-X) or (Y) or ScaleX(Width, ...) or UserControl.hDC (prop access) the expression is not lvalue (in compiler lingo) so it cannot be converted to a Variant w/ VT_BYREF flag and that is the reason why Render on the dispinterface works in this case. It works with Single/Double/String variables too (any type other that Long) becase these are implicitly cast to Long i.e. CLng(dblWidth) by the compiler so again are not lvalues and Variants are not flagged w/ VT_BYREF.
Render on IPicture is the honey-badger version of the two and works whatever you throw at it and that is what I'm using and frankly everyone should use too.
Summary: Render on IPictureDisp fails when passing local variables/parameters of the correct (Long) data-type because the VB6 compiler makes an extra effort to pass VT_BYREF flagged Variants. The reason this extra effort is allowed is because in typelibs the paramters for dispinterface are *not* described with ByRef/ByVal mode of passing per se (as for dual interfaces). The actual bug is in the IPictureDisp::Invoke implementation in oleaut32.dll
cheers,
</wqw>
Last edited by wqweto; Jul 14th, 2019 at 08:15 AM.
Here is a snippet from a recent submission to this form
thinBasic Code:
Private Sub UserControl_Paint()
If mGIF0 Is Nothing Then
Line (0, 0)- _
(ScaleWidth - ScaleX(1, vbPixels, ScaleMode), _
ScaleHeight - ScaleY(1, vbPixels, ScaleMode)), _
, _
B
Else
With mGIF0
.Render hDC, _
0, _
0, _
ScaleX(.Width, vbHimetric, vbPixels), _
ScaleY(.Height, vbHimetric, vbPixels), _
0, _
.Height, _
.Width, _
-.Height, _
ByVal 0&
. . .
Notice that this is directly calling Render on StdPicture (i.e. on IPictureDisp) and it *does* work fine because all params are either a retval from a property/method or constant literals. First param hDC is a property of the current UserControl, then some numeric literals, then two method calls of ScaleX/Y, more consts and finally .Width/.Height are properties of the very StdPicture.
The moment for instance hDC is declared a local Long variable the Render call will fail with type mismatch which is a very misleading error message in this case.