IDirect3DDevice7::ComputeSphereVisibility

The IDirect3DDevice7::ComputeSphereVisibility method calculates the visibility (complete, partial, or no visibility) of an array of spheres within the current viewport for this device.

HRESULT ComputeSphereVisibility( 
  LPD3DVECTOR lpCenters,         
  LPD3DVALUE  lpRadii,           
  DWORD       dwNumSpheres,      
  DWORD       dwFlags,           
  LPDWORD     lpdwReturnValues   
); 

Parameters

lpCenters

Array of D3DVECTOR structures describing the center point for each sphere, in world-space coordinates.

lpRadii

Array of D3DVALUE variables that represent the radius for each sphere.

dwNumSpheres

Number of spheres. This value must be greater than 0.

dwFlags

Not currently used; set to 0.

lpdwReturnValues

Array of DWORD values. The array need not be initialized, but it must be large enough to contain a DWORD for each sphere being tested. When the method returns, each element in the array contains a combination of flags that describe the visibility of that sphere within the current viewport for this device. If a sphere is completely visible, the corresponding entry in lpdwReturnValues is 0. The following flags can be combined and present in the array:

Basic Clipping Flags

D3DCLIP_BACK

All vertices are clipped by the back plane of the viewing frustum.

D3DCLIP_BOTTOM

All vertices are clipped by the bottom plane of the viewing frustum.

D3DCLIP_FRONT

All vertices are clipped by the front plane of the viewing frustum.

D3DCLIP_LEFT

All vertices are clipped by the left plane of the viewing frustum.

D3DCLIP_RIGHT

All vertices are clipped by the right plane of the viewing frustum.

D3DCLIP_TOP

All vertices are clipped by the top plane of the viewing frustum.

D3DCLIP_GEN0 through D3DCLIP_GEN5

All vertices are clipped by a corresponding application-defined clipping plane.

Combination and General Flags

D3DSTATUS_CLIPINTERSECTIONALL

Combination of all CLIPINTERSECTION flags.

D3DSTATUS_CLIPUNIONALL

Combination of all CLIPUNION flags.

D3DSTATUS_DEFAULT

Combination of D3DSTATUS_CLIPINTERSECTIONALL and D3DSTATUS_ZNOTVISIBLE flags. This value is the default.

D3DSTATUS_ZNOTVISIBLE

Indicates that the rendered primitive is not visible. This flag is set or cleared by the system when rendering with z-checking enabled (see D3DRENDERSTATE_ZVISIBLE).

Clip Intersection Flags

D3DSTATUS_CLIPINTERSECTIONBACK

Logical And of the clip flags for the vertices compared to the back clipping plane of the viewing frustum.

D3DSTATUS_CLIPINTERSECTIONBOTTOM

Logical And of the clip flags for the vertices compared to the bottom of the viewing frustum.

D3DSTATUS_CLIPINTERSECTIONFRONT

Logical And of the clip flags for the vertices compared to the front clipping plane of the viewing frustum.

D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5

Logical And of the clip flags for application-defined clipping planes.

D3DSTATUS_CLIPINTERSECTIONLEFT

Logical And of the clip flags for the vertices compared to the left side of the viewing frustum.

D3DSTATUS_CLIPINTERSECTIONRIGHT

Logical And of the clip flags for the vertices compared to the right side of the viewing frustum.

D3DSTATUS_CLIPINTERSECTIONTOP

Logical And of the clip flags for the vertices compared to the top of the viewing frustum.

Clip Union Flags

D3DSTATUS_CLIPUNIONBACK

Equal to D3DCLIP_BACK.

D3DSTATUS_CLIPUNIONBOTTOM

Equal to D3DCLIP_BOTTOM.

D3DSTATUS_CLIPUNIONFRONT

Equal to D3DCLIP_FRONT.

D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5

Equal to D3DCLIP_GEN0 through D3DCLIP_GEN5.

D3DSTATUS_CLIPUNIONLEFT

Equal to D3DCLIP_LEFT.

D3DSTATUS_CLIPUNIONRIGHT

Equal to D3DCLIP_RIGHT.

D3DSTATUS_CLIPUNIONTOP

Equal to D3DCLIP_TOP.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values:

Remarks

Sphere visibility is computed by back-transforming the viewing frustum to the model space, using the inverse of the combined world, view, or projection matrices. If the combined matrix cannot be inverted (if the determinant is 0), the method fails, returning D3DERR_INVALIDMATRIX.

The following code fragment in C illustrates how you could use ComputeSphereVisibility.

D3DVECTOR center = {0,0,0};
D3DVALUE  radius = 1;
DWORD result = 0;

res = m_pd3dDevice->ComputeSphereVisibility(&center, &radius, 1, 0, &result);

if (res == D3D_OK)
{
    if (result & D3DSTATUS_CLIPINTERSECTIONALL)
    {
        // Sphere is outside
        if (result & D3DSTATUS_CLIPINTERSECTIONLEFT)
            printf("Sphere left outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONRIGHT)
            printf("Sphere right outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONTOP)
            printf("Sphere top outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONBOTTOM)
            printf("Sphere bottom outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONFRONT)
            printf("Sphere front outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONBACK)
            printf("Sphere back outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN0)
            printf("Sphere gen0 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN1)
            printf("Sphere gen1 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN2)
            printf("Sphere gen2 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN3)
            printf("Sphere gen3 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN4)
            printf("Sphere gen4 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN5)
            printf("Sphere gen5 outside\n");
        }
    else
    if (result & D3DSTATUS_CLIPUNIONALL)
    {
        // Sphere intersects the frustum
        if (result & D3DSTATUS_CLIPUNIONLEFT)
            printf("Sphere left intersect\n");
        if (result & D3DSTATUS_CLIPUNIONRIGHT)
            printf("Sphere right intersect\n");
        if (result & D3DSTATUS_CLIPUNIONTOP)
            printf("Sphere top intersect\n");
        if (result & D3DSTATUS_CLIPUNIONBOTTOM)
            printf("Sphere bottom intersect\n");
        if (result & D3DSTATUS_CLIPUNIONFRONT)
            printf("Sphere front intersect\n");
        if (result & D3DSTATUS_CLIPUNIONBACK)
            printf("Sphere back intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN0)
            printf("Sphere gen0 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN1)
            printf("Sphere gen1 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN2)
            printf("Sphere gen2 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN3)
            printf("Sphere gen3 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN4)
            printf("Sphere gen4 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN5)
            printf("Sphere gen5 intersect\n");
    }
    else
    {
        printf("Sphere is inside\n");
    }
}
else
    printf("Invalid return value\n");

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Version: Requires DirectX 7.0.
  Header: Declared in d3d.h.