Class DirectDrawSurface

public class DirectDrawSurface implements IDirectDrawSurface
{
  // Methods
  public void addAttachedSurface(DirectDrawSurface ddS);
  public void addOverlayDirtyRect(Rect r);
  public int blt(Rect dest, DirectDrawSurface ddS, Rect src,
        int flags);
  public int bltColorFill(Rect dest, int fillValue);
  public int bltFast(int dx, int dy, DirectDrawSurface ddS,
        Rect src, int trans);
  public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src,
        int flags, DDBltFx bltFx);
  public void copyBitmap(DirectDrawBitmap val, int cx, int cy,
        int dx, int dy);
  public Direct3dDevice create3DDevice(_Guid g);
  public void deleteAttachedSurface(int flags,
        DirectDrawSurface ddS);
  public void enumAttachedSurfaces(IUnknown args,
        IEnumSurfacesCallback fn);
  public void enumOverlayZOrders(int flags, IUnknown args,
        IEnumZOrdersCallback fn);
  public void flip(DirectDrawSurface ddS, int flags);
  public DirectDrawSurface getAttachedSurface(int caps);
  public int getBltStatus(int flags);
  public int getCaps();
  public DirectDrawClipper getClipper();
  public void getColorKey(int flags, DDColorKey val);
  public int getDC();
  public IUnknown getDDInterface();
  public int getFlipStatus(int flags);
  public int getOverlayPositionX();
  public int getOverlayPositionY();
  public DirectDrawPalette getPalette();
  public void getPixelFormat(DDPixelFormat pf);
  public void getSurfaceDesc(DDSurfaceDesc surface);
  public int isLost();
  public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd,
        byte[] memory);
  public void releaseDC(int hdc);
  public int restore();
  public void setClipper(DirectDrawClipper val);
  public void setColorKey(int flags, DDColorKey val);
  public void setOverlayPosition(int x, int y);
  public void setPalette(DirectDrawPalette ddp);
  public void unlock(Rect r, DDSurfaceDesc d, byte[] memory);
  public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d,
        int flags);
  public void updateOverlayDisplay(int flags);
  public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);
}

Applications use the methods of the DirectDrawSurface class to create Microsoft® DirectDraw® surface objects and work with system-level variables.

Note This class does not provide an initialize method. Use the DirectDraw.createSurface method to create and initialize DirectDrawSurface objects.

Methods

addAttachedSurface

public void addAttachedSurface(DirectDrawSurface ddS);

Attaches a surface to another surface.

Return Value:

No return value.

Parameter	Description
ddS	The DirectDrawSurface object to attach.

See Also: deleteAttachedSurface, enumAttachedSurfaces, flip

addOverlayDirtyRect

public void addOverlayDirtyRect(Rect r);

Builds the list of the rectangles that need to be updated the next time the updateOverlayDisplay method is called.

Return Value:

No return value.

Parameter	Description
r	The Rect object that needs to be updated.

Remarks:

This method is used for the software implementation. It is not needed if the overlay support is provided by the hardware.

See Also: updateOverlayDisplay

blt

public int blt(Rect dest, DirectDrawSurface ddS, Rect src, int flags);

Performs a bit block transfer.

Return Value:

Returns S_OK or 0 if the blit was set successfully; otherwise, returns an HRESULT error code. Use the DDBLT_WAIT flag to modify the return behavior as previously discussed.

Parameter	Description
dest	A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be blitted to.
ddS	The DirectDrawSurface object that is the source for the blit operation.
src	A Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from.
flags	One or more of these values: DDCOOPERATIVE_CLIPTOCOMPONENT or DDCOOPERATIVE_OFFSETTOCOMPONENT DDBLT_ALPHADEST DDBLT_ASYNC DDBLT_ALPHADESTNEG DDBLT_KEYDEST DDBLT_ALPHASRC DDBLT_KEYSRC DDBLT_ALPHASRCNEG DDBLT_WAIT

Remarks:

This method is capable of synchronous or asynchronous blits, either display memory to display memory, display memory to system memory, system memory to display memory, or system memory to system memory. The blits can be performed by using z-information, alpha information, source color keys, and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.

Typically, blt returns immediately with an error if the blitter is busy and the blit could not be set up. The DDBLT_WAIT flag can alter this behavior so that the method will either wait until the blit can be set up or another error occurs before it returns.

bltColorFill

public int bltColorFill(Rect dest, int fillValue);

Fills the given rectangle on the surface with the given fill value.

Return Value:

Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.

Parameter	Description
dest	A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be filled.
fillvalue	The fill value to fill the rectangle with.

bltFast

public int bltFast(int dx, int dy, DirectDrawSurface ddS, Rect src,
        int trans);

Performs a source copy blit or transparent blit by using a source color key or destination color key. This method always attempts an asynchronous blit if it is supported by the hardware.

Return Value:

Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.

Parameter	Description
dx
dy	The x and y coordinates to blit to on the destination surface.
ddS	The DirectDrawSurface object that is the source for the blit operation.
src	The Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from.
trans	One value of DDBLTFAST_ type, specifying the type of transfer.

Remarks:

This method works only on display memory surfaces and cannot clip when blitting. The software implementation of bltFast is 10 percent faster than the blt method. However, there is no speed difference between the two if display hardware is being used.

Typically, bltFast returns immediately with an error if the blitter is busy and the blit cannot be set up. You can use the DDBLTFAST_WAIT flag, however, if you want this method to not return until either the blit can be set up or another error occurs.

bltFx

public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src, int flags,
        DDBltFx bltFx);

This method is capable of synchronous or asynchronous blits, in one of the following formats:

• display memory to display memory
• display memory to system memory
• system memory to display memory
• system memory to system memory

The blits can be performed by using z-information, alpha information, source color keys, and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.

Return Value:

Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.

Parameter	Description
dest	A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be blitted to.
ddS	The DirectDrawSurface object that is the source for the blit operation.
src	A Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from.
flags	This parameter is currently not used and must be set to 0.
bltfx	The DDBltFx object that defines the parameters for the blit operations.

copyBitmap

public void copyBitmap(DirectDrawBitmap val, int cx, int cy, int dx,
        int dy);

Copies a bitmap.

Return Value:

No return value.

Parameter	Description
val	The DirectDrawBitmap object
cx	The bitmap's upper-left x coordinate.
cy	The bitmap's upper-left y coordinate.
dx	The bitmap's lower-right x coordinate.
dy	The bitmap's lower-right y coordinate.

create3DDevice

public Direct3dDevice create3DDevice(_Guid g);

Creates a device from the surface if you want a rendering surface. This method emulates the IUnknown interface's HRESULT QueryInterface(REFIID riid, LPVOID* obp); COM method inherited by DirectX3 COM interfaces.

Return Value:

Returns a Direct3dDevice object that acts as a rendering surface.

Parameter	Description
g	A globally unique identifier retrieved with the enumDevices method.

deleteAttachedSurface

public void deleteAttachedSurface(int flags, DirectDrawSurface ddS);

Detaches two attached surfaces. The detached surface is not released.

Return Value:

No return value.

Parameter	Description
flags	Reserved; must be 0.
ddS	The DirectDrawSurface object to detach. If this parameter is null, all attached surfaces are detached.

See Also: flip

enumAttachedSurfaces

public void enumAttachedSurfaces(IUnknown args, IEnumSurfacesCallback fn);

Enumerates all the surfaces attached to a given surface.

Return Value:

No return value.

Parameter	Description
args	Application-defined structure that is passed to the enumeration member every time it is called.
fn	Callback interface that contains callback function that will be called for each surface that is attached to this surface.

enumOverlayZOrders

public void enumOverlayZOrders(int flags, IUnknown args,
        IEnumZOrdersCallback fn);

Enumerates the overlay surfaces on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.

Return Value:

No return value.

Parameter	Description
flags	One value of DDENUMOVERLAYZ_ type.
args	User-defined context that will be passed to the callback function for each overlay surface.
fn	Callback interface that contains the callback function that will be called for each surface being overlaid on this surface.

flip

public void flip(DirectDrawSurface ddS, int flags);

Makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface.

Return Value:

No return value.

Parameter	Description
ddS	The DirectDrawSurface object that will be flipped to. The default for this parameter is null; in which case, flip cycles through the buffers in the order they are attached to each other. This parameter is used only as an override.
flags	Can be DDFLIP_WAIT.

Remarks:

This method can be called only by a surface that has the DDSCAPS_FLIP and DDSCAPS_FRONTBUFFER values set. The display memory previously associated with the front buffer is associated with the back buffer. If there is more than one back buffer, a ring is formed and the surface memory buffers cycle one step through it every time flip is called.

The ddS parameter is used in rare cases when the back buffer is not the buffer that should become the front buffer. Typically this parameter is null.

The flip method will always be synchronized with the vertical blank.

See Also: getFlipStatus

getAttachedSurface

public DirectDrawSurface getAttachedSurface(int caps);

Obtains the attached surface that has the specified capabilities.

Return Value:

Returns the DirectDrawSurface object if successful; otherwise, returns null.

Parameter	Description
caps	A value that specifies the hardware capabilities of the surface.

Remarks:

Attachments are used to connect multiple DirectDrawSurface objects into complex structures, like the ones needed to support 3D page flipping with z-buffers. This method fails if more than one surface is attached that matches the capabilities requested. In this case, the application must use the enumAttachedSurfaces method to obtain the attached surfaces.

getBltStatus

public int getBltStatus(int flags);

Obtains the blitter status.

Return Value:

Returns DD_OK if a blitter is present, DDERR_WASSTILLDRAWING if the blitter is busy.

Parameter	Description
flags	One value of DDGBS_ type.

getCaps

public int getCaps();

Retrieves the capabilities of the surface. These capabilities are not necessarily related to the capabilities of the display device.

Return Value:

Returns the hardware capabilities of the surface.

getClipper

public DirectDrawClipper getClipper();

Retrieves the DirectDrawClipper object associated with this surface.

Return Value:

Returns the DirectDrawClipper object if successful; null otherwise.

See Also: setClipper

getColorKey

public void getColorKey(int flags, DDColorKey val);

Retrieves the color key value for the DirectDrawSurface object.

Return Value:

No return value.

Parameter	Description
flags	One value of DDCKEY_ type, specifying which color key to retrieve information for.
val	The DDColorKey object that receives the current values for the specified color key of the DirectDrawSurface object.

See Also: setColorKey

getDC

public int getDC();

Creates a Graphical Device Interface-compatible handle of a device context for the surface.

Return Value:

Returns the handle of a device context.

getDDInterface

public IUnknown getDDInterface();

Retrieves an interface to the DirectDraw object that was used to create the surface.

Return Value:

Returns the IUnknown object if successful; null otherwise.

getFlipStatus

public int getFlipStatus(int flags);

Indicates whether the surface has finished its flipping process.

Return Value:

Returns DD_OK if successful, or DDERR_WASSTILLDRAWING if the surfaces has not finished its flipping process.

Parameter	Description
flags	One value of DDGFS_ type.

See Also: flip

getOverlayPositionX

public int getOverlayPositionX();

Given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the x-display coordinate of the surface.

Return Value:

Returns the x coordinate.

See Also: getOverlayPositionY, setOverlayPosition, updateOverlay

getOverlayPositionY

public int getOverlayPositionY();

Given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the y-display coordinate of the surface.

Return Value:

Returns the y coordinate.

See Also: getOverlayPositionX, setOverlayPosition, updateOverlay

getPalette

public DirectDrawPalette getPalette();

Retrieves the DirectDrawPalette structure associated with this surface.

Return Value:

Returns the DirectDrawPalette object if successful; null otherwise. This is null if no DirectDrawPalette object is associated with this surface. If the surface is the primary surface, or a back buffer to the primary surface, and the primary surface is in 8-bpp mode, this method returns the system palette.

See Also: setPalette

getPixelFormat

public void getPixelFormat(DDPixelFormat pf);

Retrieves the color and pixel format of the surface.

Return Value:

No return value.

Parameter	Description
pf	A DDPixelFormat object that receives a detailed description of the current pixel and color space format of the surface.

getSurfaceDesc

public void getSurfaceDesc(DDSurfaceDesc surface);

Retrieves a description of the surface in its current condition.

Return Value:

No return value.

Parameter	Description
surface	A DDSurfaceDesc object that receives the current description of this surface.

isLost

public int isLost();

Determines if the surface memory associated with a DirectDrawSurface object has been freed.

Return Value:

Returns DD_OK if the memory has not been freed.

Remarks:

You can use this method to reallocate surface memory. When a DirectDrawSurface object loses its surface memory, most methods perform no function.

Surfaces can lose their memory when the mode of the display card is changed, or when an application receives exclusive access to the display card and frees all of the surface memory currently allocated on the display card.

See Also: restore

lock

public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd,
        byte[] memory);

Obtains the contents of the surface memory.

Return Value:

No return value.

Parameter	Description
r	A Rect object that identifies the region of surface that is being locked.
d	A DDSurfaceDesc object that receives the relevant details about the surface.
flags	One or more values of DDLOCK_ type.
hnd	Handle of a system event that is triggered when the surface is ready to be locked.
memory	Array variable that receives the contents of the surface memory.

Remarks:

The contents of the surface memory remain valid until the corresponding the unlock method is called. Applications that change the contents must flush the changes back into system memory (use the unlock for this as well).

Your application cannot blit from a region of a surface that is locked.

Typically, lock returns immediately when a lock cannot be obtained because a blit is in progress. You can use the DDLOCK_WAIT flag if you want the method to continue trying to obtain a lock.

See Also: unlock

releaseDC

public void releaseDC(int hdc);

Releases the handle of a device context previously obtained by using the getDC method.

Return Value:

No return value.

Parameter	Description
hdc	The handle of a device context.

restore

public int restore();

Restores a surface that has been lost. This occurs when the surface memory associated with the DirectDrawSurface object has been freed.

Return Value:

Returns DD_OK is successful.

Remarks:

Surfaces can be lost because the mode of the display card was changed or because an application received exclusive access to the display card and freed all of the surface memory currently allocated on the card. When a DirectDrawSurface object loses its surface memory, many methods will return DDERR_SURFACELOST and perform no other function. The restore method will reallocate surface memory and reattach it to the DirectDrawSurface object.

A single call to this method will restore a DirectDrawSurface object's associated implicit surfaces (back buffers, and so on). An attempt to restore an implicitly created surface will result in an error. restore will not work across explicit attachments created by using the addAttachedSurface method—each of these surfaces must be restored individually.

See Also: isLost, addAttachedSurface

setClipper

public void setClipper(DirectDrawClipper val);

Attaches a DirectDrawClipper object to a DirectDrawSurface object.

Return Value:

No return value.

Parameter	Description
val	The DirectDrawClipper object that will be attached to the DirectDrawSurface object. If this parameter is null, the current DirectDrawClipper object will be detached.

Remarks:

This method is primarily used by surfaces that are being overlaid on or blitted to the primary surface. However, it can be used on any surface. After a DirectDrawClipper object has been attached and a clip list is associated with it, the DirectDrawClipper object will be used for the blt and updateOverlay operations involving the parent DirectDrawSurface object. This method can also detach a DirectDrawSurface object's current DirectDrawClipper object.

If this method is called several times consecutively on the same surface for the same DirectDrawClipper object, the reference count for the object is incremented only once. Subsequent calls do not affect the object's reference count.

See Also: getClipper

setColorKey

public void setColorKey(int flags, DDColorKey val);

Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per surface basis.

Return Value:

No return value.

Parameter	Description
flags	One value of DDCKEY_ type, specifying which color key to set.
val	A DDColorKey object that contains the new color key values for the DirectDrawSurface object.

See Also: getColorKey

setOverlayPosition

public void setOverlayPosition(int x, int y);

Changes the display coordinates of an overlay surface.

Return Value:

No return value.

Parameter	Description
x	New x-display coordinate.
y	New y-display coordinate.

See Also: getOverlayPositionX, getOverlayPositionY, updateOverlay

setPalette

public void setPalette(DirectDrawPalette ddp);

Attaches the specified DirectDrawPalette object to a surface. The surface uses this palette for all subsequent operations. The palette change takes place immediately, without regard to refresh timing.

Return Value:

No return value.

Parameter	Description
ddp	The DirectDrawPalette object that this surface should use for future operations.

Remarks:

If this method is called several times consecutively on the same surface for the same palette, the reference count for the palette is incremented only once. Subsequent calls do not effect the palette's reference count.

See Also: getPalette, com.ms.directX.DirectDraw.createPalette

unlock

public void unlock(Rect r, DDSurfaceDesc d, byte[] memory);

Notifies DirectDraw that the direct surface manipulations are complete and copies the contents of the memory buffer into the surface.

Return Value:

No return value.

Parameter	Description
r	A Rect object that identifies the region of surface that receives the changes.
d	The DDSurfaceDesc object returned by the lock method.
memory	Array variable that contains the new contents of the surface memory.

See Also: lock

updateOverlay

public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d, int flags);

Repositions or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY value set.

Return Value:

No return value.

Parameter	Description
r	A Rect object that defines the x, y, width, and height of the region on the source surface being used as the overlay.
ddS	The DirectDrawSurface that is being overlaid.
d	A Rect object that defines the x, y, width, and height of the region on the destination surface that the overlay should be moved to.
flags	One or more values of DDOVER_ type.

updateOverlayDisplay

public void updateOverlayDisplay(int flags);

Repaints the rectangles in the dirty rectangle list of all active overlays. This clears the dirty rectangle list. This method is for software emulation only—it does nothing if the hardware supports overlays.

Return Value:

No return value.

Parameter	Description
flags	Type of update to perform. Can be DDOVER_REFRESHDIRTYRECTS or DDOVER_REFRESHALL.

See Also: addOverlayDirtyRect

updateOverlayZOrder

public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);

Sets the z-order of an overlay.

Return Value:

No return value.

Parameter	Description
flags	One value of DDOVERZ_ type.
ddS	The DirectDrawSurface object to be used as a relative position in the overlay chain. This parameter is needed only for DDOVERZ_INSERTINBACKOF and DDOVERZ_INSERTINFRONTOF.

See Also: enumOverlayZOrders