CAggDrawSurface Class


		Index Topic Contents
	Previous Topic: CAggDirectDraw Class Next Topic: CAMEvent Class

CAggDrawSurface Class

This class aggregates an IDirectDrawSurface interface. Although DirectDraw® interfaces (IDirectDraw and IDirectDrawSurface) potentially have the ability to be aggregated, this feature is not yet implemented. Various parts of Microsoft® DirectShow™ require aggregation of the DirectDraw interfaces. In particular, the video renderer passes out media samples that expose IDirectDraw and IDirectDrawSurface. This class and the CAggDirectDraw class republish the methods of the DirectDraw class so that they can be aggregated.
Each member function in this class, with the exception of the constructor, SetDirectDrawSurface, and NonDelegatingQueryInterface, simply calls the corresponding method on the IDirectDrawSurface interface with the parameters passed to it.
Protected Data Members

Name Description
m_pDirectDrawSurface DirectDraw surface.

Member Functions

Name Description
CAggDrawSurface Constructs a CAggDrawSurface object.
SetDirectDrawSurface Sets the DirectDraw object to be aggregated by this class. This must be called before any of the IDirectDrawSurface interface methods can be called.

Overridable Member Functions

Name Description
NonDelegatingQueryInterface Returns an interface and increments the reference count.

Implemented IDirectDrawSurface Methods

Name Description
AddAttachedSurface Attaches a surface to another surface. Examples of possible attachments include z-buffers, alpha channels, and back buffers.
AddOverlayDirtyRect Builds up the list of the rectangles that must be updated the next time the UpdateOverlayDisplay member function is called.
Blt Performs a bit-block transfer.
BltBatch Performs a sequence of CAggDrawSurface::Blt operations from several sources to a single destination.
BltFast Performs a source copy bit-block transfer or transparent bit-block transfer using a source or destination color key.
DeleteAttachedSurface Detaches two attached surfaces.
EnumAttachedSurfaces Enumerates all the surfaces attached to a given surface.
EnumOverlayZOrders Enumerates the overlays on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.
Flip Makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the FRONTBUFFER surface.
GetAttachedSurface Finds the attached surface that has the specified capabilities.
GetBltStatus Returns the status of a bit block transfer.
GetCaps Returns the capabilities of the surface.
GetClipper Returns the DirectDrawClipper object associated with this surface.
GetColorKey Returns the color key value for the DirectDrawSurface object.
GetDC Creates a GDI-compatible hDC for the surface.
GetFlipStatus Returns OK if the surface that it is called on has finished its flipping process; otherwise, returns DDERR_WASSTILLDRAWING.
GetOverlayPosition Returns the display coordinates of the surface, given a visible, active overlay surface (DDSCAPS_OVERLAY set).
GetPalette Returns the DirectDrawPalette structure associated with this surface.
GetPixelFormat Returns the color and pixel format of the surface.
GetSurfaceDesc Returns a DDSURFACEDESC structure describing the surface in its current condition.
Initialize Initializes a DirectDrawSurface object.
IsLost Determines if the surface memory associated with a DirectDrawSurface object has been freed.
Lock Obtains a valid pointer to the surface memory.
ReleaseDC Releases a GDI-compatible hDC previously obtained through CAggDrawSurface::GetDC.
Restore Restores a surface that has been "lost." The surface memory associated with the DirectDrawSurface object has been freed.
SetClipper Attaches a DirectDrawClipper object to a DirectDrawSurface object.
SetColorKey Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per-surface basis.
SetOverlayPosition Changes the display coordinates of an overlay surface.
SetPalette Attaches the DirectDrawPalette object specified to a DirectDrawSurface.
Unlock Notifies DirectDraw that the direct surface manipulations are complete.
UpdateOverlay Repositions and/or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY bit set.
UpdateOverlayDisplay Repaints the rectangles in the dirty rectangle lists of all active overlays.
UpdateOverlayZOrder Sets an overlay's z-order. The z-order determines which overlay should be occluded when multiple overlays are displayed simultaneously.

CAggDrawSurface::CAggDrawSurface
CAggDrawSurface Class
Creates a CAggDrawSurface object.
CAggDrawSurface(
  TCHAR *pName,
  LPUNKNOWN pUnk
  );
Parameters

pName
Name of the object; used for debugging purposes.
pUnk
Pointer to the owner of this object. If non-NULL, IUnknown interface calls are delegated to this object.

Return Values

No return value.
Remarks

This member function calls the CUnknown::CUnknown base class constructor and sets the m_pDirectDrawSurface member variable to NULL.
CAggDrawSurface::NonDelegatingQueryInterface
CAggDrawSurface Class
Returns an interface and increments the reference count.
HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void ** ppv
  );
Parameters

riid
Reference identifier.
ppv
Pointer to the interface.

Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.
Remarks

This member function provides an implementation of the INonDelegatingUnknown::NonDelegatingQueryInterface method. By default it passes out references to IDirectDrawSurface and then calls the CUnknown::NonDelegatingQueryInterface member function for base class interface references. Override this class to return interfaces added in the derived class.
CAggDrawSurface::SetDirectDrawSurface
CAggDrawSurface Class
Called by the owner of this aggregation object to set the actual DirectDraw surface it is aggregating upon.
void SetDirectDrawSurface(
  LPDIRECTDRAWSURFACE pDirectDrawSurface
  );
Parameters

pDirectDrawSurface
DirectDrawSurface to be set.

Return Values

No return value.
Remarks

This member function must be called before any of the IDirectDrawSurface interface methods can be called.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
Top of Page

Name	Description
m_pDirectDrawSurface	DirectDraw surface.

Name	Description
CAggDrawSurface	Constructs a CAggDrawSurface object.
SetDirectDrawSurface	Sets the DirectDraw object to be aggregated by this class. This must be called before any of the IDirectDrawSurface interface methods can be called.

Name	Description
NonDelegatingQueryInterface	Returns an interface and increments the reference count.

Name	Description
AddAttachedSurface	Attaches a surface to another surface. Examples of possible attachments include z-buffers, alpha channels, and back buffers.
AddOverlayDirtyRect	Builds up the list of the rectangles that must be updated the next time the UpdateOverlayDisplay member function is called.
Blt	Performs a bit-block transfer.
BltBatch	Performs a sequence of CAggDrawSurface::Blt operations from several sources to a single destination.
BltFast	Performs a source copy bit-block transfer or transparent bit-block transfer using a source or destination color key.
DeleteAttachedSurface	Detaches two attached surfaces.
EnumAttachedSurfaces	Enumerates all the surfaces attached to a given surface.
EnumOverlayZOrders	Enumerates the overlays on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.
Flip	Makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the FRONTBUFFER surface.
GetAttachedSurface	Finds the attached surface that has the specified capabilities.
GetBltStatus	Returns the status of a bit block transfer.
GetCaps	Returns the capabilities of the surface.
GetClipper	Returns the DirectDrawClipper object associated with this surface.
GetColorKey	Returns the color key value for the DirectDrawSurface object.
GetDC	Creates a GDI-compatible hDC for the surface.
GetFlipStatus	Returns OK if the surface that it is called on has finished its flipping process; otherwise, returns DDERR_WASSTILLDRAWING.
GetOverlayPosition	Returns the display coordinates of the surface, given a visible, active overlay surface (DDSCAPS_OVERLAY set).
GetPalette	Returns the DirectDrawPalette structure associated with this surface.
GetPixelFormat	Returns the color and pixel format of the surface.
GetSurfaceDesc	Returns a DDSURFACEDESC structure describing the surface in its current condition.
Initialize	Initializes a DirectDrawSurface object.
IsLost	Determines if the surface memory associated with a DirectDrawSurface object has been freed.
Lock	Obtains a valid pointer to the surface memory.
ReleaseDC	Releases a GDI-compatible hDC previously obtained through CAggDrawSurface::GetDC.
Restore	Restores a surface that has been "lost." The surface memory associated with the DirectDrawSurface object has been freed.
SetClipper	Attaches a DirectDrawClipper object to a DirectDrawSurface object.
SetColorKey	Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per-surface basis.
SetOverlayPosition	Changes the display coordinates of an overlay surface.
SetPalette	Attaches the DirectDrawPalette object specified to a DirectDrawSurface.
Unlock	Notifies DirectDraw that the direct surface manipulations are complete.
UpdateOverlay	Repositions and/or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY bit set.
UpdateOverlayDisplay	Repaints the rectangles in the dirty rectangle lists of all active overlays.
UpdateOverlayZOrder	Sets an overlay's z-order. The z-order determines which overlay should be occluded when multiple overlays are displayed simultaneously.