CLCREATEEVENTFROMGLS(3clc)

💖 CLCREATEEVENTFROMGLS 💖

okay bestie, we're in the 3clc OpenCL manual, and today's main character is a lil function called clCreateEventFromGLsyncKHR — it's giving "bridge between OpenCL and OpenGL" and honestly? iconic behavior. let's get into it 🦋

---

✨ NAME ✨

clCreateEventFromGLsyncKHR — creates an event object linked to an OpenGL sync object. no cap, that's the whole gig 💅

cl_event clCreateEventFromGLsyncKHR(cl_context context, GLsync sync,
                                    cl_int *errcode_ret);

---

🌸 PARAMETERS 🌸

• context — a valid OpenCL context, and it has to be one created from an OpenGL context or a share group, using the cl_khr_gl_sharing(3clc) extension. like, it's not optional, it's the vibe check 🫶
• sync — the name of a sync object in the GL share group associated with context. that's the GL-side bestie you're linking to ✨

---

🎀 DESCRIPTION 🎀

so here's the tea: you can make an event object by linking it to an OpenGL sync object. once you do that, completion of this event object is equivalent to waiting for completion of the fence command associated with the linked GL sync object. same energy, same finish line, periodt 💅

---

👑 NOTES 👑

when you query a linked event's parameters with clGetEventInfo(3clc), you get these values back:

• the CL_EVENT_COMMAND_QUEUE of a linked event is NULL, because the event is not associated with any OpenCL command queue. it's unbothered, unqueued, free 🦋
• the CL_EVENT_COMMAND_TYPE of a linked event is CL_COMMAND_GL_FENCE_SYNC_OBJECT_KHR, which means the event is associated with a GL sync object rather than an OpenCL command. it's a GL girlie at heart 💜
• the CL_EVENT_COMMAND_EXECUTION_STATUS of a linked event is either CL_SUBMITTED — meaning the fence command associated with the sync object has not yet completed — or CL_COMPLETE, meaning the fence command has completed. it's either "not yet bestie" or "we're done here" 💀

clCreateEventFromGLsyncKHR performs an implicit clRetainEvent(3clc) on the returned event object. creating a linked event object also places a reference on the linked GL sync object, and when the event object is deleted, that reference gets removed from the GL sync object. so like, it's all tracked, the refcounts are balancing, we love to see it 🧚

⚠️ important one: events returned from clCreateEventFromGLsyncKHR may only be consumed by clEnqueueAcquireGLObjects(3clc). passing such events to any other CL API will generate a CL_INVALID_EVENT error. do not pass go, do not collect $200 🙈

---

🔥 ERRORS 🔥

returns a valid OpenCL event object and errcode_ret is set to CL_SUCCESS if the event object is created successfully. otherwise it returns a NULL value, with one of these error values coming back in errcode_ret:

• CL_INVALID_CONTEXT if context is not a valid context, or was not created from a GL context. wrong context, boo 🍓
• CL_INVALID_GL_OBJECT if sync is not the name of a sync object in the GL share group associated with context. like, who is that? never met her 💀

---

🌈 SPECIFICATION 🌈

OpenCL Specification[1] — the receipts, as always ✨

---

💜 SEE ALSO 💜

cl_khr_gl_event(3clc), clEnqueueAcquireGLObjects(3clc), clRetainEvent(3clc) — go read these next, iykyk 👑

---

⭐ AUTHORS ⭐

The Khronos Group. kings of the spec fr fr 👑

---

🫶 COPYRIGHT 🫶

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 62, section 9.8.4 - Additions to Chapter 5

---

and that's the whole page bestie 💖 brought to you by The Khronos Group, dated 01/14/2021, filed under CLCREATEEVENTFROMGLS(3clc). slay, go forth and link your events 🌟