[VB] stdPicture Render (How To)

[LaVolpe]

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.

Private Function RenderStdPicture(theTarget As Variant, thePic As StdPicture, _
                             Optional ByVal destX As Long, Optional ByVal destY As Long, _
                             Optional ByVal destWidth As Long, Optional ByVal destHeight As Long, _
                             Optional ByVal srcX As Long, Optional ByVal srcY As Long, _
                             Optional ByVal srcWidth As Long, Optional ByVal srcHeight As Long, _
                             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 Long, Height As Long, 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
    Height = ScaleY(thePic.Height, vbHimetric, vbPixels)
    
    On Error Resume Next
    If IsObject(theTarget) Then         ' passed object? If so, set scalemode if needed
        If theTarget Is Nothing Then Exit Function
        If ParamScaleMode = vbUser Then ParamScaleMode = theTarget.ScaleMode
        destDC = theTarget.hDC
    ElseIf IsNumeric(theTarget) Then    ' passed hDC? If so, set scalemode if needed
        If ParamScaleMode = vbUser Then ParamScaleMode = vbPixels
        destDC = Val(theTarget)
        Centered = False                ' only applicable if theTarget is a VB object
    Else
        Exit Function                   ' unhandled; abort
    End If
    If Err Then                         ' checks above generated an error; probably passing object without scalemode property?
        Err.Clear
        Exit Function
    End If        
 
    If destWidth Then                   ' calculate destination width in pixels from ParamScaleMode
        destWidth = ScaleX(destWidth, ParamScaleMode, vbPixels) * ZoomFactor
    Else
        destWidth = Width * ZoomFactor
    End If
    If destHeight Then                  'calculate destination height in pixels from ParamScaleMode
        destHeight = ScaleY(destHeight, ParamScaleMode, vbPixels) * ZoomFactor
    Else
        destHeight = Height * ZoomFactor
    End If
                                        ' get destX,destY in pixels from ParamScaleMode
    If destX Then destX = ScaleX(destX, ParamScaleMode, vbPixels)
    If destY Then destY = ScaleY(destY, ParamScaleMode, vbPixels)
    If Centered Then                    ' Offset destX,destY if centering
        destX = (ScaleX(theTarget.ScaleWidth, theTarget.ScaleMode, vbPixels) - destWidth) / 2 + destX
        destY = (ScaleY(theTarget.ScaleHeight, theTarget.ScaleMode, vbPixels) - destHeight) / 2 + destY
    End If
                                        ' setup source coords/bounds and convert to vbHimetrics
    If srcX Then srcX = ScaleX(srcX, ParamScaleMode, vbHimetric)
    If srcY Then srcY = ScaleY(srcY, ParamScaleMode, vbHimetric)
    If srcWidth Then srcWidth = ScaleX(srcWidth, ParamScaleMode, vbHimetric) Else srcWidth = thePic.Width
    If srcHeight Then srcHeight = ScaleY(srcHeight, ParamScaleMode, vbHimetric) Else srcHeight = thePic.Height
    
    If Err Then                         ' passed bad parameters or
        Err.Clear                       ' passed object that has no ScaleMode property (i.e., VB Frame)
    Else
        With thePic                     ' render, the "Or 0&" below are required else mismatch errors occur
            .Render destDC Or 0&, destX Or 0&, destY Or 0&, destWidth Or 0&, destHeight Or 0&, _
                srcX Or 0&, .Height - srcY, srcWidth Or 0&, -srcHeight, ByVal 0&
        End With                        ' return success/failure
        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

   ' destDC can be any DC
    Dim thePic As stdPicture
    Set thePic = LoadPicture("C:\Images\Screenshots\image1002.jpg")
    With thePic
        .Render destDC Or 0&, 0&, 0&, ScaleX(.Width, vbHimetric, vbPixels), ScaleY(.Height, vbHimetric, vbPixels), _
            0&, .Height, .Width, -.Height, ByVal 0&
    End With

[Merri]

Here is a more compact solution than the Or 0&:

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.


Sample attachment project here.

[Merri]

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.

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:

    ' 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))

[LaVolpe]

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:

    Sprite.Render (TargetDC), (X), (Y), (Width), (Height), _
        0, Sprite.Height, Sprite.Width, -Sprite.Height, ByVal 0&

[Merri]

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

[ThePiper]

What is the .Render method of the stdPicture object and how does one use it.

Thank you, LaVolpe and Merri, for this excellent lesson!

[Ben321]

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.