Edit

ID3D12Device::CreateSharedHandle method (d3d12.h)

  • Article

Creates a shared handle to a heap, resource, or fence object.

Syntax

HRESULT CreateSharedHandle(
  [in]           ID3D12DeviceChild         *pObject,
  [in, optional] const SECURITY_ATTRIBUTES *pAttributes,
                 DWORD                     Access,
  [in, optional] LPCWSTR                   Name,
  [out]          HANDLE                    *pHandle
);

Parameters

[in] pObject

Type: ID3D12DeviceChild*

A pointer to the ID3D12DeviceChild interface that represents the heap, resource, or fence object to create for sharing. The following interfaces (derived from ID3D12DeviceChild) are supported:

[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.

Access

Type: DWORD

Currently the only value this parameter accepts is GENERIC_ALL.

[in, optional] Name

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 12 Return Codes topic.

Remarks

Both heaps and committed resources can be shared. Sharing a committed resource shares the implicit heap along with the committed resource description, such that a compatible resource description can be mapped to the heap from another device.

For Direct3D 11 and Direct3D 12 interop scenarios, a shared fence is opened in DirectX 11 with the ID3D11Device5::OpenSharedFence method, and a shared resource is opened with the ID3D11Device::OpenSharedResource1 method.

For Direct3D 12, a shared handle is opened with the ID3D12Device::OpenSharedHandle or the ID3D12Device::OpenSharedHandleByName method.

Requirements

Requirement Value
Target Platform Windows
Header d3d12.h
Library D3D12.lib
DLL D3D12.dll

See also

ID3D12Device