CDXBaseSurface Class

The CDXBaseSurface class is used to simplify the creation of procedural surfaces. An Active Template Library (ATL) COM object derived from this class inherits most of the default functionality of an object that can be used as both a transform and a surface. Procedural surfaces are usually created by calling the IDXSurfaceFactory::CreateSurface method, specifying the pFormatID parameter equal to the object's CLSID, and specifying DXSF_FORMAT_IS_CLSID in the dwFlags parameter.

To use this base class, you must override the CreateARGBPointer, DeleteARGBPointer, and SurfaceCLSID member functions. All other function overrides are optional.

This class inherits from the CDXBaseNTo1 class and the IDXSurface and IDXSurfaceInit interfaces.

Data Members

m_dwAppData

A 32-bit value that can be used to store custom data about the surface.

m_dwStatusFlags

A value that contains flags from the DXLOCKSURF and DXSURFSTATUS enumerations that gives users information about your surface. Procedural surfaces created from this base class always set the DXSURF_READONLY flag set to TRUE.

m_Height

The height of the surface, in pixels. The default value is zero, so you should use the OnSetSize function to change this value prior to rendering the surface.

m_Width

The width of the surface, in pixels. The default value is zero, so you should use the OnSetSize function to change this value prior to rendering the surface.

Member Functions

CreateARGBPointer Allocates an ARGB read pointer object.

DeleteARGBPointer Frees an ARGB read pointer object.

OnGetObjectSize Called by the base class to determine the object's size, in bytes.

OnSetSize Sets the width and height of the surface.

OnSurfacePick Determines whether any part of the surface is located at the specified point.

SampleFormatEnum Retrieves the native pixel format of the surface.

SurfaceCLSID Retrieves the CLSID of the surface.

WorkProc Called by the transform base class to enable the surface to function as a transform.

CDXBaseSurface::CreateARGBPointer

CDXBaseSurface Class

Allocates an ARGB read pointer object.

Syntax

virtual HRESULT CreateARGBPointer(
	CDXBaseSurface *pSurface,
	CDXBaseARGBPtr **ppPtr
);

Parameters

pSurface
[in] Pointer to the CDXBaseSurface object.

ppPtr
[out] Address of a pointer to the newly created CDXBaseARGBPtr class object.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Derived classes must override this virtual function.
A procedural surface object is required to define an ARGB sample access object that supports the IDXARGBReadPtr interface. The CDXBaseARGBPtr class can be used to simplify this.

See Also

CDXBaseARGBPtr, CDXBaseSurface::DeleteARGBPointer

CDXBaseSurface::DeleteARGBPointer

CDXBaseSurface Class

Frees an ARGB read pointer object.

Syntax

virtual void DeleteARGBPointer(
	CDXBaseARGBPtr *pPtr
);

Parameters

[in] pPtr

Pointer to the CDXBaseARGBPtr object to delete.

Return Value

No return value.

Remarks

Derived classes must override this virtual function.

See Also

CDXBaseSurface::CreateARGBPointer

CDXBaseSurface::OnGetObjectSize

CDXBaseSurface Class

Called by the base class to determine the object's size, in bytes.

Syntax

virtual ULONG OnGetObjectSize(void);

Return Value

Returns the size of the surface, in bytes.

Remarks

The default implementation returns sizeof( *this ). If the object allocates resources, the derived class should override this method to provide more accurate information. This information helps the container manage memory more accurately.

CDXBaseSurface::OnSetSize

CDXBaseSurface Class

Sets the width and height of the surface.

Syntax

virtual HRESULT OnSetSize(
	ULONG Width,
	ULONG Height
);

Parameters

Width
[in] New width of the surface, in pixels.

Height
[in] New height of the surface, in pixels.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The derived class can override this virtual function to perform necessary computations when the size of the surface changes. The base class will only call this function from the IDXSurfaceInit::InitSurface method. You can call it from other interfaces you implement (for example, IDXTScaleOutput). The default implementation stores the width and height in the m_Width and m_Height data members of CDXBaseSurface, and calls CDXBaseNto1::SetDirty to increment the generation ID.

See Also

CDXBaseNTo1::SetDirty, IDXSurfaceInit::InitSurface, IDXTScaleOutput

CDXBaseSurface::OnSurfacePick

CDXBaseSurface Class

Determines whether any part of the surface is located at the specified point.

Syntax

virtual HRESULT OnSurfacePick(
	const CDXDBnds &OutPoint,
	ULONG &ulInputIndex,
	CDXDVec &InVec
);

Parameters

OutPoint
Coordinates of the point on the output surface to test.

ulInputIndex
Not used for procedural surfaces.

InVec
Not used for procedural surfaces.

Return Value

If the sample in the output space has an alpha value greater than zero, DXT_S_HITOUTPUT should be returned. Otherwise, S_FALSE should be returned, indicating a miss.

Remarks

Procedural surfaces can only know if there is a sample located at the specified point. There is no input surface to map the point back to, so ulInputIndex and InVec should return NULL.

See Also

IDXSurfacePick

CDXBaseSurface::SampleFormatEnum

CDXBaseSurface Class

Retrieves the native pixel format of the surface.

Syntax

virtual DXSAMPLEFORMATENUM SampleFormatEnum(void);

Return Value

Returns the pixel format for your surface as a member of the DXSAMPLEFORMATENUM enumeration. The base class default value is (DXPF_NONSTANDARD | DXPF_TRANSPARENCY | DXPF_TRANSLUCENCY).

Remarks

Procedural surfaces should return DXPF_NONSTANDARD. This indicates that users cannot get direct access to the samples because they are procedurally generated when read. This is all that is needed if the output samples will always have an alpha value of 255. If the output samples can have alpha values of 0 or 255, then the DXPF_TRANSPARENCY flag should be set for the return value. If the output samples can have alpha values ranging from 0 through 255, then the DXPF_TRANSLUCENCY flag should be set as well. This information is used to optimize sample processing in other routines.

CDXBaseSurface::SurfaceCLSID

CDXBaseSurface Class

Retrieves the CLSID of the surface.

Syntax

virtual const GUID &SurfaceCLSID(void);

Return Value

Returns a GUID for the derived surface's CLSID.

Remarks

Derived classes must override this virtual function.
The base class calls this method to determine the class identifier of the derived class. This is used mainly for COM persistence support.

CDXBaseSurface::WorkProc

CDXBaseSurface Class

Called by the transform base class to enable the surface to function as a transform.

Syntax

virtual HRESULT WorkProc(
	const CDXTWorkInfoNTo1 &WI,
	BOOL *pbContinueProcessing
);

Parameters

WI
[in] Work procedure information structure that contains the rendering request details.

pbContinueProcessing
[in] Pointer to a Boolean value that is TRUE as long as the function is supposed to continue the rendering request.

Return Value

Returns S_OK for success, or an implementation-dependent value on error.

Remarks

The base class calls this method when the procedural surface is being used as a transform. It is called to generate a block of output samples and write them to the specified destination surface. The default implementation of this method simply calls the DXBitBlt helper function with the specified input and output regions. In turn, this object is locked like a procedural surface and pixels are generated through the IDXARGBReadPtr interface. Usually, you don't need to override this method.

See Also

CDXBaseNTo1::WorkProc

CreateARGBPointer	Allocates an ARGB read pointer object.
DeleteARGBPointer	Frees an ARGB read pointer object.
OnGetObjectSize	Called by the base class to determine the object's size, in bytes.
OnSetSize	Sets the width and height of the surface.
OnSurfacePick	Determines whether any part of the surface is located at the specified point.
SampleFormatEnum	Retrieves the native pixel format of the surface.
SurfaceCLSID	Retrieves the CLSID of the surface.
WorkProc	Called by the transform base class to enable the surface to function as a transform.