Class DirectDraw

public class DirectDraw implements IDirectDraw
{
  // Methods
  public DirectDrawClipper createClipper(int flags);
  public Direct3d createD3D();
  public DirectDrawPalette createPalette(int flags, byte[] pe);
  public DirectDrawPalette createPalette(int flags);
  public DirectDrawPalette createPalette(int flags, Color[] pe);
  public DirectDrawPalette createPalette(int flags,
        PaletteEntry[] pe);
  public DirectDrawSurface createSurface(DDSurfaceDesc dd);
  public DirectDrawSurface duplicateSurface(DirectDrawSurface ddIn);
  public void enumDisplayModes(int d, DDSurfaceDesc s,
        IUnknown args, IEnumModesCallback fn);
  public void flipToGDISurface();
  public int getAvailableTotalMem(int[] ddsCaps);
  public void getCaps(DDCaps driverCaps, DDCapsFx driverCapsFx,
        DDCaps helCaps, DDCapsFx helCapsFx);
  public void getDisplayMode(DDSurfaceDesc surface);
  public int getFourCCCodes(int[] size);
  public int getFreeMem(int [] ddsCaps);
  public DirectDrawSurface getGDISurface();
  public int getMonitorFrequency();
  public int getNumFourCCCodes();
  public int getScanLine();
  public int getVerticalBlankStatus();
  public DirectDrawPalette loadPaletteFromBitmap(String bName);
  public void restoreDisplayMode();
  public void setCooperativeLevel(Component c, int flags);
  public void setCooperativeLevel(int hdl, int flags);
  public void setDisplayMode(int w, int h, int bpp, int ref,
        int mode);
  public int systemBpp();
  public int tickCount();
  public void waitForVerticalBlank(int flags, int handle);
}

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

Methods

createClipper

public DirectDrawClipper createClipper(int flags);

Creates a DirectDrawClipper object.

Return Value:

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

Parameter	Description
flags	This parameter is currently not used and must be set to 0.

Remarks:

The DirectDrawClipper object can be attached to a DirectDrawSurface and used during blt and updateOverlay operations.

See Also: com.ms.directX.DirectDrawSurface

createD3D

public Direct3d createD3D();

Creates a Microsoft® Direct3D® object.

Return Value:

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

createPalette

public DirectDrawPalette createPalette(int flags, byte[] pe);

Creates a DirectDrawPalette object for this DirectDraw object.

Return Value:

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

Parameter	Description
flags	One or more values of the DDPCAPS_ type.
pe	The array variable that contains the data describing the initial value for each palette entry.

createPalette

public DirectDrawPalette createPalette(int flags);

Creates a palette and fills it with standard halftone entries.

Return Value:

Returns the DirectDrawPalette object if successful; otherwise, returns null. Currently, only DDPCAPS_8BIT and DDPCAPS_INITIALIZE are valid arguments for the flags parameter.

Parameter	Description
flags	One or more values of DDPCAPS_ type.

createPalette

public DirectDrawPalette createPalette(int flags, Color[] pe);

Creates a DirectDrawPalette object for this DirectDraw object.

Return Value:

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

Parameter	Description
flags	One or more values of the DDPCAPS_ type.
pe	The array variable that contains the data describing the initial color value for each palette entry.

createPalette

public DirectDrawPalette createPalette(int flags, PaletteEntry[] pe);

Creates a DirectDrawPalette object for this DirectDraw object.

Return Value:

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

Parameter	Description
flags	One or more values of DDPCAPS_ type.
pe	The array variable that contains a PaletteEntry object describing each palette entry.

createSurface

public DirectDrawSurface createSurface(DDSurfaceDesc dd);

Creates a DirectDrawSurface object for this DirectDraw object.

Return Value:

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

Parameter	Description
dd	The DDSurfaceDesc object that describes the requested surface.

duplicateSurface

public DirectDrawSurface duplicateSurface(DirectDrawSurface ddIn);

Duplicates a DirectDrawSurface object.

Return Value:

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

Parameter	Description
ddIn	The DirectDrawSurface object to be duplicated.

Remarks:

This method creates a new DirectDrawSurface object that represents the same surface memory as an existing DirectDrawSurface object. This duplicate can be used just like the original object. The surface memory is released after the last object referencing it is released. A primary surface, 3D surface, or implicitly created surface cannot be duplicated.

enumDisplayModes

public void enumDisplayModes(int d, DDSurfaceDesc s, IUnknown args,
        IEnumModesCallback fn);

Enumerates all of the display modes the hardware exposes through the DirectDraw object that are compatible with a provided surface description. If null is passed for the surface description, all exposed modes are enumerated.

Return Value:

No return value.

Parameter	Description
d	This flag Can be DDEDM_REFRESHRATES.
s	A DDSurfaceDesc object that will be checked against available modes. If the value of this parameter is null, all modes are enumerated.
args	Application-defined data that will be passed to each enumeration member.
fn	The callback interface containing the callback function that the enumeration procedure will call every time a match is found.

Remarks:

This method enumerates the backBufferCount field of the DDSurfaceDesc class. If you use the setDisplayMode method to set the refresh rate of a new mode, you must use enumDisplayModes to enumerate the backBufferCount field.

See Also: getDisplayMode, setDisplayMode, restoreDisplayMode

flipToGDISurface

public void flipToGDISurface();

Makes the surface that GDI writes to the primary surface.

Return Value:

No return value.

Remarks:

This method can be called at the end of a page-flipping application to ensure that the display memory that the GDI is writing to is visible to the user.

See Also: getGDISurface

getAvailableTotalMem

public int getAvailableTotalMem(int[] ddsCaps);

Retrieves the total available amount of display memory.

Return Value:

Returns the amount of memory.

Parameter	Description
ddsCaps	An array of the values found in the DDSCaps class.

Remarks:

A display adapter card may make no distinction between two different memory types.

For example, the adapter might use the same portion of display memory to store z-buffers and textures. So, allocating one type of surface (for example, a z-buffer) can affect the amount of display memory available for another type of surface (for example, textures). Therefore, it is best to first allocate an application's fixed resources (such as front, back, and z-buffers) before determining how much memory is available for dynamic use, such as texture mapping.

getCaps

public void getCaps(DDCaps driverCaps, DDCapsFx driverCapsFx,
        DDCaps helCaps, DDCapsFx helCapsFx);

Fills in the capabilities of the device driver for the hardware and the hardware emulation layer (HEL).

Return Value:

No return value.

Parameter	Description
driverCaps	A DDCaps object that receives the capabilities of the hardware, as reported by the device driver.
driverCapsFx	A DDCapsFx object that receives the capabilities of the hardware, as reported by the device driver. The DDCapsFx class is used with classes that contain more than 256 bytes of member data.
helCaps	A DDCaps object that receives the capabilities of the HEL.
helCapsFx	A DDCapsFx object that receives the capabilities of the HEL. The DDCapsFx class is used with classes that contain more than 256 bytes of member data.

getDisplayMode

public void getDisplayMode(DDSurfaceDesc surface);

Retrieves the current display mode.

Return Value:

No return value.

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

Remarks:

An application should not save the information returned by this method to restore the display mode on clean-up. The application should use the restoreDisplayMode method to restore the mode on clean-up, which avoids mode-setting conflicts that could arise in a multiprocess environment.

See Also: setDisplayMode, restoreDisplayMode, enumDisplayModes

getFourCCCodes

public int getFourCCCodes(int[] size);

Retrieves the FourCC codes supported by the DirectDraw object. This method can also retrieve the number of codes supported.

Return Value:

Returns an address of an array that contains the codes.

Parameter	Description
size	The array variable that receives the FourCC codes supported by this DirectDraw object.

getFreeMem

public int getFreeMem(int [] ddsCaps);

Retrieves the amount of display memory currently free.

Return Value:

Returns the amount of free display memory.

Parameter	Description
ddsCaps	An array of the values found in the DDSCaps class.

Remarks:

This method provides only a snapshot of the current display-memory state. The amount of free display memory is subject to change as surfaces are created and released. Therefore, you should use the free memory value only as an approximation.

getGDISurface

public DirectDrawSurface getGDISurface();

Retrieves the DirectDrawSurface object that currently represents the surface memory that the Graphical Device Interface (GDI) is treating as the primary surface.

Return Value:

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

See Also: flipToGDISurface

getMonitorFrequency

public int getMonitorFrequency();

Retrieves the frequency of the monitor being driven by the DirectDraw object. The frequency value is returned in Hz multiplied by 100. For example, 60Hz is returned as 6000.

Return Value:

Returns the monitor frequency.

getNumFourCCCodes

public int getNumFourCCCodes();

Retrieves the number of FourCC codes in the array getFourCCCodes specifies.

Return Value:

Returns the number of FourCCCodes.

getScanLine

public int getScanLine();

Retrieves the scan line that is currently being drawn on the monitor.

Return Value:

Returns the scan line.

See Also: getVerticalBlankStatus, waitForVerticalBlank

getVerticalBlankStatus

public int getVerticalBlankStatus();

Retrieves the status of the vertical blank.

Return Value:

Returns 1 if a vertical blank is occurring; otherwise, returns 0.

Remarks:

To synchronize with the vertical blank, use the waitForVerticalBlank method.

See Also: getScanLine, waitForVerticalBlank

loadPaletteFromBitmap

public DirectDrawPalette loadPaletteFromBitmap(String bName);

Loads a palette.

Return Value:

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

Parameter	Description
bName	Name of the bitmap that contains the palette to load.

restoreDisplayMode

public void restoreDisplayMode();

Resets the mode of the display device hardware for the primary surface to what it was before the setDisplayMode method was called. Exclusive-level access is required to use this method.

Return Value:

No return value.

See Also: setDisplayMode, enumDisplayModes, setCooperativeLevel

setCooperativeLevel

public void setCooperativeLevel(Component c, int flags);

Determines the top-level behavior of the application (the primary method that does so).

Return Value:

No return value.

Parameter	Description
c	The Component used for the application.
flags	One or more values of DDSCL_ type.

Remarks:

You must call the show() or addNotify() method before calling setCooperativeLevel

See Also: setDisplayMode, compact, enumDisplayModes

setCooperativeLevel

public void setCooperativeLevel(int hdl, int flags);

Serves as a helper for the setCooperativeLevel(Component, int) method and remains for use by more advanced programmers. The setCooperativeLevel method also determines the top-level behavior of the application.

Return Value:

No return value.

Parameter	Description
hdl	The Microsoft® Windows® handle used for the application. Applications can use DirectDraw with multiple windows. Therefore, setCooperativeLevel does not require a window handle to be specified if the application is requesting the DDSCL_NORMAL mode. By passing a null to the window handle, all the windows can be used simultaneously in normal Windows mode.
flags	One or more values of the DDSCL_ type.

See Also: setDisplayMode, compact, enumDisplayModes

setDisplayMode

public void setDisplayMode(int w, int h, int bpp, int ref, int mode);

Sets the mode of the display-device hardware.

Return Value:

No return value.

Parameter	Description
w	The width of the new mode.
h	The height of the new mode.
bpp	The bits per pixel of the new mode.
ref	The refresh rate of the new mode.
mode	Reserved; value must be 0.

Remarks:

The setCooperativeLevel method must be used to set exclusive-level access before the mode can be changed. If other applications have created a DirectDrawSurface object on the primary surface and the mode is changed, those applications' primary surface objects return DDERR_SURFACELOST until they are restored.

See Also: restoreDisplayMode, getDisplayMode, enumDisplayModes, setCooperativeLevel

systemBpp

public int systemBpp();

Retrieves the current system's bits-per-pixel value.

Return Value:

Returns the bits-per-pixel value.

tickCount

public int tickCount();

Retrieves the current tick count.

Return Value:

Returns the tick count.

waitForVerticalBlank

public void waitForVerticalBlank(int flags, int handle);

Assists the application tosynchronize itself with the vertical-blank interval.

Return Value:

No return value.

Parameter	Description
flags	One value of DDWAITVB_ type; flag specifies how long to wait for the vertical blank.
handle	The handle of the event to be triggered when the vertical blank begins.

See Also: getVerticalBlankStatus, getScanLine