CLCREATEFROMGLRENDER(3clc)

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

🌸 NAME 🌸

bestie, meet clCreateFromGLRenderbuffer — she makes an OpenCL 2D image object out of an OpenGL renderbuffer object. that's the whole gig. and she eats every time 💅

cl_mem clCreateFromGLRenderbuffer(cl_context context,
                                  cl_mem_flags flags,
                                  GLuint renderbuffer,
                                  cl_int * errcode_ret);

(this is the <cyan>3clc</cyan> manual btw, OpenCL Manual energy, iykyk ✨)

🎀 PARAMETERS 🎀

  • context — a valid OpenCL context that was created from an OpenGL context. like, she needs the GL glue or she's not coming to the party. no cap.
  • flags — a bit-field specifying usage info. go peek at the table over in clCreateBuffer(3clc) for what flags even means. ⚠️ only these three are allowed here: CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY, and CL_MEM_READ_WRITE — the ones specified in that table at clCreateBuffer(3clc). that's it, that's the list, don't try anything else 🙈
  • renderbuffer — the name of a GL renderbuffer object. 🫶 heads up: the renderbuffer storage must be specified before the image object can be created, periodt. the renderbuffer format and dimensions that OpenGL defines are what get used to create the 2D image object. and only GL renderbuffers whose internal formats map to an appropriate image channel order and data type — the ones in the table of supported Image Channel Order Values and the table of supported Image Channel Data Types for cl_image_format(3clc) — can be used to create the 2D image object. so check the tables, bestie 📋
  • errcode_ret — returns an appropriate error code, all the deets below. if errcode_ret is NULL, then no error code comes back at all. she's quiet like that 🤫

💫 DESCRIPTION 💫

okay so here's the tea, and it's a little scary: if the state of a GL renderbuffer object gets modified through the GL API — like, changes to the dimensions or the format used to represent pixels of the GL renderbuffer via appropriate GL API calls such as glRenderbufferStorage — while a corresponding CL image object exists, then subsequent use of the CL image object will result in undefined behavior. 💀 not a vibe. don't do that.

you can use clRetainMemObject(3clc) and clReleaseMemObject(3clc) to retain and release the image objects. those are your girls for keeping the refcount situation cute ✨

the table below (Table 9.4) is the ✨canon✨ list of GL texture internal formats and their matching CL image formats. if a GL texture object with an internal format from this table gets successfully created by OpenGL, then a mapping to one of the corresponding CL image format(s) in that table is guaranteed. texture objects created with other OpenGL internal formats may — but are not guaranteed to — have a mapping to a CL image format. and if such mappings do exist, they're guaranteed to preserve all color components, data types, and at least the number of bits/component that OpenGL actually allocated for that format. slay 🌈

  • GL_RGBA8 → CL_RGBA, CL_UNORM_INT8 or CL_BGRA, CL_UNORM_INT8
  • GL_RGBA, GL_UNSIGNED_INT_8_8_8_8_REV → CL_RGBA, CL_UNORM_INT8
  • GL_BGRA, GL_UNSIGNED_INT_8_8_8_8_REV → CL_BGRA, CL_UNORM_INT8
  • GL_RGBA16 → CL_RGBA, CL_UNORM_INT16
  • GL_RGBA8I, GL_RGBA8I_EXT → CL_RGBA, CL_SIGNED_INT8
  • GL_RGBA16I, GL_RGBA16I_EXT → CL_RGBA, CL_SIGNED_INT16
  • GL_RGBA32I, GL_RGBA32I_EXT → CL_RGBA, CL_SIGNED_INT32
  • GL_RGBA8UI, GL_RGBA8UI_EXT → CL_RGBA, CL_UNSIGNED_INT8
  • GL_RGBA16UI, GL_RGBA16UI_EXT → CL_RGBA, CL_UNSIGNED_INT16
  • GL_RGBA32UI, GL_RGBA32UI_EXT → CL_RGBA, CL_UNSIGNED_INT32
  • GL_RGBA16F, GL_RGBA16F_ARB → CL_RGBA, CL_HALF_FLOAT
  • GL_RGBA32F, GL_RGBA32F_ARB → CL_RGBA, CL_FLOAT

🦋 ERRORS 🦋

she returns a valid non-zero OpenCL image object and errcode_ret gets set to CL_SUCCESS if the image object is created successfully. 🎉 otherwise she returns a NULL value, and one of these error values comes back in errcode_ret:

  • CL_INVALID_CONTEXT — if context is not a valid context, or was not created from a GL context. 😭
  • CL_INVALID_VALUE — if the values specified in flags are not valid.
  • CL_INVALID_GL_OBJECT — if renderbuffer is not a GL renderbuffer object, or if the width or height of renderbuffer is zero.
  • CL_INVALID_IMAGE_FORMAT_DESCRIPTOR — if the OpenGL renderbuffer internal format does not map to a supported OpenCL image format.
  • CL_INVALID_OPERATION — if renderbuffer is a multi-sample GL renderbuffer object. (not her thing, sorry 🚫)
  • CL_OUT_OF_RESOURCES — if there's a failure to allocate resources required by the OpenCL implementation on the device.
  • CL_OUT_OF_HOST_MEMORY — if there's a failure to allocate resources required by the OpenCL implementation on the host.

👑 SPECIFICATION 👑

OpenCL Specification[1] — yes, the actual spec, main character behaviour 📖

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

⭐ NOTES ⭐

  1. OpenCL Specification — page 53, section 9.7.4 - CL Image Objects -> GL Renderbuffers 📚

and that's the whole page bestie!! this was the 3clc OpenCL Manual, brought to you by The Khronos Group, dated 01/14/2021, page CLCREATEFROMGLRENDER(3clc). go forth and map those renderbuffers, you absolute icon 💖✨🎀🦋

📦 where this page comes from