DOC: EngPlgBlt for Rotating a Bitmap Surface

ID: Q152118

The information in this article applies to:

Microsoft Win32 Device Driver Kit (DDK) for Windows NT, version 3.51

SUMMARY

There is an error in the online documentation for the EngPlgBlt function, and it is quite un-intuitive. This function is used for both Win32 display drivers and Win32 printer drivers.

MORE INFORMATION

The parameter "pptfxDest" that defines the parallelogram of the destination surface is actually a pointer to an array of type POINTFIX (not POINTFX) as defined in %DDK%\inc\winddi.h:


   typedef LONG FIX;
   typedef struct  _POINTFIX
   {
       FIX   x;
       FIX   y;
   } POINTFIX, *PPOINTFIX;

The members x and y are of type LONG. It is implied that they must be in 28.4 fixed notation. Thus, to properly use this function, you need to shift the LONG values by 4 bits to the left to comply with the 28.4 notation.

NOTE: If the Destination surface is less than the Source surface, the image will shrink and rotate accordingly. If the Destination surface is greater than the Source surface, the image will also stretch and rotate accordingly. Otherwise, the surface will just rotate accordingly.

SAMPLE


////////////////////////////////////////////////////////////////////////// 
// 
// This routine simply rotates a surface's bitmap 90 degrees to the right.
// Note: DISPDBG() is from %DDK%\src\video\displays\vga\debug.*
// 
   BOOL
   RotateSurface(
      SURFOBJ *psoSource
      )
   {
       PPDEV       ppdev;
       HSURF       hSurf;
       SURFOBJ    *psoDest;
       SIZEL       sizl;
       RECTL       rclSrc;
       POINTFIX    pfxDest[3];

       // 
       // get the pointer to our DEVDATA structure
       // 
       ppdev = (PPDEV)psoSource->dhpdev;

       // 
       // create the rotated bitmap
       // 
       sizl.cx = psoSource->sizlBitmap.cy;
       sizl.cy = psoSource->sizlBitmap.cx;

       if ((hSurf = (HSURF)EngCreateBitmap(
               sizl,
               sizl.cx,
                  psoSource->iBitmapFormat,
                  psoSource->fjBitmap,
                  NULL)) == NULL )
      {
         DISPDBG((0, "EngCreateBitmap FAILED; GetLastError() = %d\n",
   GetLastError() ));
            return(FALSE);
      }

       if (!EngAssociateSurface(
         hSurf,
            ppdev->hdevEng, // Note: we must have stored this earlier
            0L) )
      {
         DISPDBG((0, "EngAssociateSurface FAILED; GetLastError() = %d\n",
   GetLastError() ));
         EngDeleteSurface(hSurf);
            return(FALSE);
      }

       // 
       // setup the destination pointfx array
       // 
       pfxDest[0].x = sizl.cx << 4; // A
       pfxDest[0].y = 0;
       pfxDest[1].x = sizl.cx << 4;    // B
       pfxDest[1].y = sizl.cy << 4;
       pfxDest[2].x = 0;         // C
       pfxDest[2].y = 0;

       // 
       // setup the source rectangle
       // 
       rclSrc.top    = 0;
       rclSrc.left   = 0;
       rclSrc.bottom = psoSource->sizlBitmap.cy;
       rclSrc.right  = psoSource->sizlBitmap.cx;

       // 
       // rotate the original bitmap 90 degrees to the right onto the new
   bitmap
       // 
       if (!EngPlgBlt(
         psoDest,
            psoSource,
            NULL, NULL, NULL, NULL, NULL,
               &pfxDest[0],
               &rclSrc,
               NULL,
               HALFTONE ))
       {
            DISPDBG((0, "EngPlgBlt FAILED; GetLastError() = %d\n",
   GetLastError() ));
            EngDeleteSurface(hSurf);
            return(FALSE);
       }

       // 
       // you now have your rotated bitmap in psoDest until you delete it.
       // 

       EngDeleteSurface(hSurf);

       return(TRUE);
   }

REFERENCES

For additional information on the iMode parameter, please see the following article in the Microsoft Knowledge Base:

Q140674 DOCERR: Incorrect iModes Parameter to DDI StretchBlt Functions

Additional query words: 3.51

Keywords : kbdocfix ntddkprnt ntddkvideo
Version : 3.51
Platform : NT WINDOWS
Issue type :