Edit

ID3D11Fence::CreateSharedHandle method (d3d11_3.h)

  • Article

Creates a shared handle to a fence object.

This method is equivalent to the Direct3D 12 ID3D12Device::CreateSharedHandle method, and it applies in scenarios involving interoperation between Direct3D 11 and Direct3D 12. In DirecX 11, you can open the shared fence handle with the ID3D11Device5::OpenSharedFence method. In DirecX 12, you can open the shared fence handle with the ID3D12Device::OpenSharedHandle method.

Syntax

HRESULT CreateSharedHandle(
  [in, optional] const SECURITY_ATTRIBUTES *pAttributes,
                 DWORD                     dwAccess,
  [in, optional] LPCWSTR                   lpName,
  [out]          HANDLE                    *pHandle
);

Parameters

[in, optional] pAttributes

Type: const SECURITY_ATTRIBUTES*

A pointer to a SECURITY_ATTRIBUTES structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines whether child processes can inherit the returned handle.

Set this parameter to NULL if you want child processes that the application might create to not inherit the handle returned by CreateSharedHandle, and if you want the resource that is associated with the returned handle to get a default security descriptor.

The lpSecurityDescriptor member of the structure specifies a SECURITY_DESCRIPTOR for the resource. Set this member to NULL if you want the runtime to assign a default security descriptor to the resource that is associated with the returned handle. The ACLs in the default security descriptor for the resource come from the primary or impersonation token of the creator. For more info, see Synchronization Object Security and Access Rights.

dwAccess

Type: DWORD

Currently the only value this parameter accepts is GENERIC_ALL.

[in, optional] lpName

Type: LPCWSTR

A NULL-terminated UNICODE string that contains the name to associate with the shared heap. The name is limited to MAX_PATH characters. Name comparison is case-sensitive.

If Name matches the name of an existing resource, CreateSharedHandle fails with DXGI_ERROR_NAME_ALREADY_EXISTS. This occurs because these objects share the same namespace.

The name can have a "Global" or "Local" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\). For more information, see Kernel Object Namespaces. Fast user switching is implemented using Terminal Services sessions. Kernel object names must follow the guidelines outlined for Terminal Services so that applications can support multiple users.

The object can be created in a private namespace. For more information, see Object Namespaces.

[out] pHandle

Type: HANDLE*

A pointer to a variable that receives the NT HANDLE value to the resource to share. You can use this handle in calls to access the resource.

Return value

Type: HRESULT

Returns S_OK if successful; otherwise, returns one of the following values:

  • DXGI_ERROR_INVALID_CALL if one of the parameters is invalid.
  • DXGI_ERROR_NAME_ALREADY_EXISTS if the supplied name of the resource to share is already associated with another resource.
  • E_ACCESSDENIED if the object is being created in a protected namespace.
  • E_OUTOFMEMORY if sufficient memory is not available to create the handle.
  • Possibly other error codes that are described in the Direct3D 11 Return Codes topic.

Remarks

In order to create a shared handle for the specified fence, the fence must have been created with either the D3D11_FENCE_FLAG_SHARED or D3D11_FENCE_FLAG_SHARED_CROSS_ADAPTER flags. For more information see the D3D11_FENCE_FLAG enumeration.

Requirements

Requirement Value
Target Platform Windows
Header d3d11_3.h
Library D3D11.lib
DLL D3D11.dll

See also

ID3D11Fence