CLCREATEFROMD3D10TEX(3clc)

📦
version 1.0~svn33624 · 3 versions
, in ubuntu jammy, ubuntu noble

CLCREATEFROMD3D10TEX 💅✨

okay bestie, this is the 3clc manual page for clCreateFromD3D10Texture3DKHR, and it's giving "OpenCL meets Direct3D" crossover episode energy. let's get into it 🎀

✨ NAME ✨

clCreateFromD3D10Texture3DKHR — creates an OpenCL 3D image object from a subresource of a Direct3D 10 3D texture. literally exactly what it says on the tin, no cap. 💖

and here's the signature, character for character, don't touch it:

cl_mem clCreateFromD3D10Texture3DKHR(cl_context context,
                                     cl_mem_flags flags,
                                     ID3D10Texture3D *resource,
                                     UINT subresource,
                                     cl_int *errcode_ret);

🌸 PARAMETERS 🌸

  • context — a valid OpenCL context, and it has to be one that was created from a Direct3D 10 device. like, it's gotta be the right friend group, yk? 🫶
  • flags — a bit-field that specifies usage info. your options here are CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY, or CL_MEM_READ_WRITE. (if you want the whole lore on this, go peek at the table in clCreateBuffer(3clc) — it's right there.) 🦋
  • resource — a pointer to the Direct3D 10 3D texture you wanna share. sharing is caring fr fr 💖
  • subresource — the subresource of resource that you're sharing. yes, you have to pick one, it's not a buffet. 🍓
  • errcode_ret — an appropriate error code. but heads up: if errcode_ret is NULL, then no error code is returned at all. so if you pass NULL and something goes wrong, you just… won't hear about it. not me finding out the hard way 😭

💜 NOTES 💜

the width, height and depth of the returned OpenCL 3D image object are determined by the width, height and depth of subresource subresource of resource. so it's lowkey just inheriting the shape from where it came from, iconic behavior. ✨

and the channel type and order of the returned OpenCL 3D image object are determined by the format of resource — it's all laid out in the table of Direct3D 10 and corresponding OpenCL image formats. (that's the table, bestie, iykyk 👑)

one more thing, and it's important: this call will increment the internal Direct3D reference count on resource. and then that internal Direct3D reference count on resource gets decremented when the OpenCL reference count on the returned OpenCL memory object drops to zero. so the ref counts are keeping each other in check, mutuals supporting mutuals. 💅

more of this page is coming, don't go anywhere bestie 🎀

Okay so, here's the ✨translator✨ bestie, because Direct3D 10 and OpenCL do not speak the same format language and somebody has to do the emotional labour of matching them up. Below is the full roster of Direct3D 10 formats and the OpenCL image format each one maps to, written as (channel order, channel data type). No cap, every single one is here. 🫶

🌈 The four-channel girlies (RGBA) 🌈

  • DXGI_FORMAT_R32G32B32A32_FLOAT → CL_RGBA, CL_FLOAT
  • DXGI_FORMAT_R32G32B32A32_UINT → CL_RGBA, CL_UNSIGNED_INT32
  • DXGI_FORMAT_R32G32B32A32_SINT → CL_RGBA, CL_SIGNED_INT32

(breather 💅)

  • DXGI_FORMAT_R16G16B16A16_FLOAT → CL_RGBA, CL_HALF_FLOAT
  • DXGI_FORMAT_R16G16B16A16_UNORM → CL_RGBA, CL_UNORM_INT16
  • DXGI_FORMAT_R16G16B16A16_UINT → CL_RGBA, CL_UNSIGNED_INT16
  • DXGI_FORMAT_R16G16B16A16_SNORM → CL_RGBA, CL_SNORM_INT16
  • DXGI_FORMAT_R16G16B16A16_SINT → CL_RGBA, CL_SIGNED_INT16

(another lil breather, hydrate bestie 🍓)

  • DXGI_FORMAT_R8G8B8A8_UNORM → CL_RGBA, CL_UNORM_INT8
  • DXGI_FORMAT_R8G8B8A8_UINT → CL_RGBA, CL_UNSIGNED_INT8
  • DXGI_FORMAT_R8G8B8A8_SNORM → CL_RGBA, CL_SNORM_INT8
  • DXGI_FORMAT_R8G8B8A8_SINT → CL_RGBA, CL_SIGNED_INT8

🦋 Two channels, twice the vibe (RG) 🦋

  • DXGI_FORMAT_R32G32_FLOAT → CL_RG, CL_FLOAT
  • DXGI_FORMAT_R32G32_UINT → CL_RG, CL_UNSIGNED_INT32
  • DXGI_FORMAT_R32G32_SINT → CL_RG, CL_SIGNED_INT32

(tiny pause, we're doing great ✨)

  • DXGI_FORMAT_R16G16_FLOAT → CL_RG, CL_HALF_FLOAT
  • DXGI_FORMAT_R16G16_UNORM → CL_RG, CL_UNORM_INT16
  • DXGI_FORMAT_R16G16_UINT → CL_RG, CL_UNSIGNED_INT16
  • DXGI_FORMAT_R16G16_SNORM → CL_RG, CL_SNORM_INT16
  • DXGI_FORMAT_R16G16_SINT → CL_RG, CL_SIGNED_INT16

(okay one more pause, you're eating this 🎀)

  • DXGI_FORMAT_R8G8_UNORM → CL_RG, CL_UNORM_INT8
  • DXGI_FORMAT_R8G8_UINT → CL_RG, CL_UNSIGNED_INT8
  • DXGI_FORMAT_R8G8_SNORM → CL_RG, CL_SNORM_INT8
  • DXGI_FORMAT_R8G8_SINT → CL_RG, CL_SIGNED_INT8

👑 Solo channel, main character energy (R) 👑

  • DXGI_FORMAT_R32_FLOAT → CL_R, CL_FLOAT
  • DXGI_FORMAT_R32_UINT → CL_R, CL_UNSIGNED_INT32
  • DXGI_FORMAT_R32_SINT → CL_R, CL_SIGNED_INT32

(breather 💜)

  • DXGI_FORMAT_R16_FLOAT → CL_R, CL_HALF_FLOAT
  • DXGI_FORMAT_R16_UNORM → CL_R, CL_UNORM_INT16
  • DXGI_FORMAT_R16_UINT → CL_R, CL_UNSIGNED_INT16
  • DXGI_FORMAT_R16_SNORM → CL_R, CL_SNORM_INT16
  • DXGI_FORMAT_R16_SINT → CL_R, CL_SIGNED_INT16

(last lil breather, promise 🌸)

  • DXGI_FORMAT_R8_UNORM → CL_R, CL_UNORM_INT8
  • DXGI_FORMAT_R8_UINT → CL_R, CL_UNSIGNED_INT8
  • DXGI_FORMAT_R8_SNORM — maps to CL_R, CL_SNORM_INT8 💜
  • DXGI_FORMAT_R8_SINT — maps to CL_R, CL_SIGNED_INT8 💜

okay so general info about sharing memory objects with Direct3D 10, incoming 👇

The whole goal of this extension is to give you interoperability between OpenCL and Direct3D 10. It's designed to function analogously to the OpenGL interoperability, iykyk. If an implementation supports this extension, the string "cl_khr_d3d10_sharing" will be present in the CL_PLATFORM_EXTENSIONS or CL_DEVICE_EXTENSIONS string described in the table of allowed values for param_name for clGetDeviceInfo(3clc). That's literally your vibe check ✨

As currently proposed, the interfaces for this extension would be provided in cl_d3d10.h.

This next bit is about the OpenCL functions that let applications use Direct3D 10 resources as OpenCL memory objects — which is so efficient for sharing data between OpenCL and Direct3D 10. You can use the OpenCL API to run kernels that read and/or write memory objects that are also Direct3D 10 resources. An OpenCL image object may be created from a Direct3D 10 texture resource. An OpenCL buffer object may be created from a Direct3D 10 buffer resource. And OpenCL memory objects may be created from Direct3D 10 objects if and only if the OpenCL context has been created from a Direct3D 10 device. no shortcuts bestie 🫶

🌸 Lifetime of Shared Objects 🌸

An OpenCL memory object created from a Direct3D 10 resource stays valid as long as the corresponding Direct3D 10 resource has not been deleted. If the Direct3D 10 resource is deleted through the Direct3D 10 API, subsequent use of the OpenCL memory object will result in undefined behavior, including but not limited to possible OpenCL errors, data corruption, and program termination. 💀

fr fr, do not delete the Direct3D 10 resource out from under your OpenCL memory object. that's the whole plot twist you don't want.

The successful creation of a cl_context against a Direct3D 10 device specified via the context create parameter CL_CONTEXT_D3D10_DEVICE_KHR will increment the internal Direct3D reference count on the specified Direct3D 10 device. The internal Direct3D reference count on that Direct3D 10 device will be decremented when the OpenCL reference count on the returned OpenCL context drops to zero. the way that it just... balances itself 👑

The OpenCL context and corresponding command-queues are dependent on the existence of the Direct3D 10 device from which the OpenCL context was created. If the Direct3D 10 device is deleted through the Direct3D 10 API, subsequent use of the OpenCL context will result in undefined behavior, including but not limited to possible OpenCL errors, data corruption, and program termination. 💀

💥 ERRORS 💥

Returns CL_SUCCESS returns a valid non-zero OpenCL buffer object and errcode_ret is set to CL_SUCCESS if the buffer object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

  • CL_INVALID_CONTEXT — if context is not a valid context. 🙈
  • CL_INVALID_VALUE — if the values specified in flags are not valid, or if subresource is not a valid subresource index for resource.
  • CL_INVALID_D3D10_RESOURCE_KHR — if resource is not a Direct3D 10 texture resource, if resource was created with the D3D10_USAGE flag D3D10_USAGE_IMMUTABLE, if a resource is a multisampled texture, if cl_mem from subresource subresource of resource has already been created using clCreateFromD3D10Texture3DKHR, or if context was not created against the same Direct3D 10 device from which resource was created.
  • CL_INVALID_IMAGE_FORMAT_DESCRIPTOR — if the Direct3D 10 texture format of resource is not a value listed in the above table of Direct3D 10 and corresponding OpenCL image formats, or if the Direct3D 10 texture format of resource does not map to a supported OpenCL image format.
  • CL_OUT_OF_HOST_MEMORY — if there is a failure to allocate resources required by the OpenCL implementation on the host.

📖 SPECIFICATION 📖

OpenCL Specification[1]

👀 SEE ALSO 👀

👑 AUTHORS 👑

The Khronos Group

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

and that's the whole page bestie, we ate and left no crumbs 💅✨ this one came from The Khronos Group, version-dated 01/14/2021, filed under CLCREATEFROMD3D10TEX(3clc). go forth and share those textures responsibly 🦋💖

📦 where this page comes from