SURFOBJ hsurf HANDLE

folks, can some one please explain to me in plain English how to use the SURFOBJ->hsurf handle - that is, it is apparently a handle to either a DIBSECTION, a BITMAP if a GDI managed surface or it’s a HANDLE to my device managed surface if I chose for my driver to tell UniDrv to create a device-managed surface in DriverDMS. Got it - I’m fairly confident on that subject. But I get lost as follows.

  1. Assuming GID Managed surface
    a. Is it a GDI kernel based HANDLE where I can retrieve BITMAP or DIBSECTION through GetObject? (doesn’t work).
    b. I tried to determine the type of HANDLE with GetObjectType (doesn’t work - returns 0).
    c. Tried casting to HBITMAP. (doesn’t work).

  2. Assuming Device-managed surface
    a. So DriverDMS creates a device-managed surface and returns the handle to it in SURFOBJ->hsurf. But doesn’t allocate space for it. What good is the handle then? Is it a place holder rather then a useful handle?

How exactly does one get at what GDI rendered on the surface in either scenario (device managed or gdi managed)?

I understand, it may depend on the method that I am within (unidrv printer rendering plug-in). It may depend on the hooking functions and/or HOOK_-flags that I set. I think I tried every combination under the sun and still I can’t hear the music through the noise. I am very grateful in advance to anyone that can help me hear the lovely music.

Questions restated simply -

  1. How to access to the rendered bitmap (rendered by GDI) on a GDI managed surface through ((target)SURFOBJ)->hsurf no matter the IPrintOEMUni(x):: or the Hooked Function I want to access it from.

  2. What good is the SURFOBJ->hsurf handle to a device managed surface if DriverDMS encapsulates the surface creation process and doesn’t allow my driver to associate the hsurf handle to some object that my driver creates. Ben didn’t you read the well written detailed, error free documentation that in no way contradicts itself and makes no assumptions? Ah… No! I haven’t seen this animal at the WDK zoo. In this case what exactly is hsurf pointing too? Wait! don’t say it’s a device managed surface because that assumes that the device driver had something to do with creating it. Perhaps in the old days before IPrintOEMUni(x) when one called EngAssociateSurface…

I sincerely appreciate a nudge or a kick in the ankle to put me back in alignment with the universe.

-Ben

When you have a device-managed surface, you’ll call EngCreateBitmap in DrvEnableSurface to create something that GDI can draw on in your fallbacks. EngCreateBitmap returns an HSURF, which gets stored in the SURFOBJ. In an odd twist, the HSURF can be used to fetch the associated SURFOBJ (via EngLockSurface). Now, much of what I know is ancient lore from the days of XPDM. In a Unidrv environment, the class driver is handling many details.

“ancient lore” is generally synonymous with “wisdom” in my “software development encyclopedia” Tim.

Thank you Tim, you hit on the core issue that I’m struggling with. I’m using the IPrintOemUni[2|3] interfaces and my driver is a UniDrv rendering plug-in. In this case, I understand that it’s Unidrv that “internally” calls either EngCreateBitmap or EngCreateDeviceSurface based on the HOOK_-prefix flags that I set in DriverDMS. And indeed UniDrv does create something as I get something other then NULL in hsurf in my HOOK’d functions.

hsurf is documented to be a HANDLE to either a Bitmap or DIB for a GDI managed surface or a HANDLE to whatever I choose if I set to use the device managed surface. But accessing the object through the handle is what brought me to ‘osr’. That’s just pure mad magic on how one does that.

Note that I don’t have an exposed DrvEnableSurface as part of the IPrintOemUni(x) interfaces. I also do not have an option to intercept or otherwise do anything during the surface creation process - or do I? I have considered, but have not tried, to add the DrvEnableSurface hooking function to my HOOKed callbacks to see if it is called by UniDrv but I read in these forum someplace that the rendering plug-in doesn’t call DrvEnableSurface. Must try it.

And I hear you saying that it’s “YOU” meaning “ME” who creates the surface with EngCreateBitmap or EngCreateDeviceSurface in DrvEnableSurface even in a rendering plug-in? Can you confirm that this is true when using the Rendering Plug-in interface model for the driver? Because the documentation suggests otherwise “at least to me” and hence my eyebrow is now favorably, severely raised in adoration of your “wisdom”. Of course your wisdom and my comprehensive abilities play second fiddle to the quality and completeness of the Microsoft documentation, there’s now way it’s wrong or incomplete and God forbit I suggest it’s in conflict with itself. Yeap - clear as mud!

Thanks for the note on EngLockSurface. I need to ponder on that one for a bit. To have the hsurf, I already have the SURFOBJ. So what “actually” is “hsurf” if I can use it to get the SURFOBJ that hsurf belongs too. I say it was the chicken that came first. No wait, maybe it was the egg… darn it Tim?

Thanks
Ben

I already have the SURFOBJ. So what “actually” is “hsurf” if I can use it to get the SURFOBJ that hsurf belongs too. I say it was the chicken that came first. No wait, maybe it was the egg.

You’re exactly right. I went back to my old XPDM drivers, and the HSURF isn’t referenced very often. When it is, it’s used to get the SURFOBJ, which includes a pointer to the pixels themselves, and in a display driver that is usually what you want.