Package panamagl.platform.macos

Class CGLContext_macOS

java.lang.Object

panamagl.opengl.AGLContext

panamagl.platform.macos.CGLContext_macOS

All Implemented Interfaces:

panamagl.opengl.GLContext

public class CGLContext_macOS
extends panamagl.opengl.AGLContext
implements panamagl.opengl.GLContext

The CGL API is a low-level, platform-independent API for creating, managing, and rendering 2D and 3D graphics in macOS and other operating systems. It provides functions for creating and managing graphics contexts, setting up rendering pipelines, and rendering 2D and 3D graphics.

Help on deadlocks

There are a few reasons why you might experience a deadlock when using FBO (Framebuffer Object) offscreen rendering and opening a JPanel in a CGL (Core Graphics Library) context. Some possible causes of this issue include:

• Concurrent access to the CGL context: If multiple threads or processes are trying to access the CGL context concurrently, it can cause a deadlock. To avoid this, you should use synchronization mechanisms such as mutexes or semaphores to ensure that only one thread or process is accessing the CGL context at a time.
• Incomplete initialization: If the CGL context or FBO offscreen rendering is not fully initialized before the JPanel is opened, it can cause a deadlock. Make sure that all necessary initialization steps have been completed before opening the JPanel.
• Incorrect use of locking and unlocking: The CGL context must be locked before it can be used for rendering or other graphics operations, and unlocked when the operations are complete. If the CGL context is not properly locked and unlocked, it can cause a deadlock. Make sure that the CGL context is locked and unlocked correctly.
• Incorrect rendering order: If you are using multiple rendering contexts or FBOs, it is important to render them in the correct order to avoid deadlocks. Make sure that you are rendering the contexts or FBOs in the correct sequence to avoid deadlocks.

Help on debugging

Hint : to debug this class, invoke a program using it with flag -Danamagl.platform.macos.CGLContext_macOS Use the Console app and select system.log

Author:

Martin Pernollet

See Also:

• invalid reference

  in JOGL

Field Summary

Fields

Modifier and Type	Field	Description
protected MemorySegment	attribs
protected MemorySegment	context
protected boolean	debug
protected MemorySegment	numberOfPixels
protected int	pixelFormatLength
protected MemorySegment	pixelFormatPtr

Fields inherited from class panamagl.opengl.AGLContext

arena, initialized, profile

Constructor Summary

Constructors

Constructor	Description
CGLContext_macOS()

Method Summary

Modifier and Type	Method	Description
protected void	choosePixelFormat()	Configure pixel format attributes and retrieve pixel format and max number of sample per pixel.
protected MemorySegment	createContext()	Create a context, assuming the pixel attributes and format have already been defined.
protected int	describePixelFormat(MemorySegment pixelFormat, int attribute, int pixNum)	Retrieve a pixel format value for a given attribute.
void	destroy()
protected void	destroyContext(MemorySegment context)	CGLDestroyContext is used to destroy an OpenGL rendering context created with CGLCreateContext.
protected MemorySegment	getCurrentContext()
void	init()
protected void	lockContext(MemorySegment context)	In the CGL API, a CGL context must be locked before it can be used for rendering or other graphics operations.
void	makeCurrent()
void	release()
protected void	releaseContext(MemorySegment context)
protected void	setCurrentContext(MemorySegment context)
protected void	setCurrentContextZero()
protected void	throwExceptionUponError(String info, int status)	Check the status returned by CGL invocation and throw a runtime exception if not success
protected void	unlockContext(MemorySegment context)

Methods inherited from class panamagl.opengl.AGLContext

getProfile, initArena, isInitialized, setProfile

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface panamagl.opengl.GLContext

getProfile, isInitialized, setProfile

Field Details

attribs

protected MemorySegment attribs

pixelFormatPtr

protected MemorySegment pixelFormatPtr

numberOfPixels

protected MemorySegment numberOfPixels

pixelFormatLength

protected int pixelFormatLength

context

protected MemorySegment context

debug

protected boolean debug

Constructor Details

CGLContext_macOS

public CGLContext_macOS()

Method Details

init

public void init()

Specified by:

init in interface panamagl.opengl.GLContext

destroy

public void destroy()

Specified by:

destroy in interface panamagl.opengl.GLContext

makeCurrent

public void makeCurrent()

release

public void release()

createContext

protected MemorySegment createContext()

Create a context, assuming the pixel attributes and format have already been defined. The context is supposed to valid when the function returns since errors are checked. Any error is thrown as a RuntimeException. Possible source of errors are clarified below.

Errors

kCGLBadPixelFormat

There are several reasons why calling CGLCreateContext can trigger a kCGLBadPixelFormat error. Here are some possible reasons:

• The pixel format specified is not valid: Make sure that the pixel format you're passing to CGLCreateContext is valid and supported by the system. You can use the CGLDescribePixelFormat function to inspect the properties of a given pixel format.
• The pixel format specified is not compatible with the requested OpenGL profile: Make sure that the OpenGL profile you're requesting is compatible with the pixel format you're using. For example, if you're requesting a Core 3.2 OpenGL profile, you need to use a pixel format that supports that profile version.
• The requested OpenGL feature set is not compatible with the requested OpenGL profile: If you're requesting a Core OpenGL profile, make sure that the OpenGL functions you're using are compatible with that profile. For example, immediate-mode OpenGL functions such as glBegin and glEnd are not supported in Core OpenGL profiles.
• There is an OpenGL context conflict: Make sure that there are no other active OpenGL contexts on the same thread or in the same application that could conflict with your context.

kCGLBadCodeModule

The kCGLBadCodeModule error that you're getting when calling CGLCreateContext usually indicates that there's a problem with the graphics driver or framework that you're using. Here are some possible reasons why you might be seeing this error:

• Incorrect graphics driver or framework installation: Make sure that you have the correct graphics driver and framework installed on your system. If you're using an external graphics card, make sure that the driver for that card is installed and up-to-date.
• Incompatible graphics driver or framework: Make sure that the graphics driver or framework you're using is compatible with your system and the version of macOS you're running.
• Corrupt graphics driver or framework: If the graphics driver or framework installation is corrupt, it can cause issues when creating an OpenGL context. Try reinstalling the graphics driver or framework to see if that resolves the issue.
• Conflicting third-party software: Some third-party software can interfere with the graphics driver or framework and cause issues when creating an OpenGL context. Try disabling any third-party software that might be causing conflicts.

SUPPOSED DATA STRUCTURE

A CGLContext is a data structure in macOS's Core Graphics framework that represents an OpenGL rendering context. It is used to manage and execute OpenGL commands within a particular graphics context. The CGLContext data structure is defined in the CGLTypes.h header file and contains the following fields:

• CGLError error: An error code that indicates whether any errors have occurred in the context.
• CGLPixelFormatObj pixelFormat: A reference to a CGLPixelFormat object that describes the attributes of the pixel format for the context.
• CGLShareGroupObj shareGroup: A reference to a CGLShareGroup object that provides a mechanism for sharing OpenGL objects and resources between contexts.
• void* contextID: A platform-specific identifier for the context that is used by the underlying graphics system to manage and execute OpenGL commands.
• CGLContextObj prev: A reference to the previous context in a linked list of contexts.
• CGLContextObj next: A reference to the next context in the linked list.
• void* reserved: A reserved field for future use.

Overall, the CGLContext data structure provides a way to encapsulate and manage the state of an OpenGL rendering context, including the pixel format, sharing resources, and the context itself.

destroyContext

protected void destroyContext(MemorySegment context)

CGLDestroyContext is used to destroy an OpenGL rendering context created with CGLCreateContext.

Errors

When CGLDestroyContext returns a kCGLBadContext error code, it means that the context provided to CGLDestroyContext is not a valid OpenGL rendering context. There are several possible reasons why CGLDestroyContext might return a kCGLBadContext error code. Some of the common ones are:

• The context was not created with CGLCreateContext.
• The context has already been destroyed.
• The context was created on a different thread.
• The OpenGL driver encountered an error.

To diagnose the specific cause of the kCGLBadContext error code, you may need to consult the macOS system logs (Console app).

lockContext

protected void lockContext(MemorySegment context)

In the CGL API, a CGL context must be locked before it can be used for rendering or other graphics operations. This is done using the CGLLockContext() function.

Errors

The kCGLBadContext error can be generated by the CGLLockContext function in the following scenarios:

• Invalid context handle: The CGLLockContext function requires a valid context handle to lock the context for rendering. If the handle is not valid or has been deallocated, the function returns the kCGLBadContext error.
• Context not current: The function requires that the context specified by the context handle is the current context.
• Context already locked.
• Thread not owner: CGLLockContext can be called from any thread, but only the thread that locks the context can make GL calls to that context. If a thread other than the one that locked the context attempts to make a GL call, then the function returns the kCGLBadContext error.
• Graphics hardware issue: A kCGLBadContext error can also be caused by a graphics hardware issue, such as a driver error or a failure to allocate memory on the GPU.

unlockContext

protected void unlockContext(MemorySegment context)

setCurrentContext

protected void setCurrentContext(MemorySegment context)

setCurrentContextZero

protected void setCurrentContextZero()

getCurrentContext

protected MemorySegment getCurrentContext()

releaseContext

protected void releaseContext(MemorySegment context)

choosePixelFormat

protected void choosePixelFormat()

Configure pixel format attributes and retrieve pixel format and max number of sample per pixel. Signature of CGLChoosePixelFormat used in this implementation :

• attribs: A pointer to an array of integers representing the attributes that you want to specify for the pixel format. The array should be terminated with a value of 0 to indicate the end of the attribute list. You can find a full list of pixel format attributes in the CGLPixelFormat.h header file.
• pix: A pointer to a CGLPixelFormatObj object where the chosen pixel format will be stored. If the function call is successful, this object will be a valid pixel format object that you can use to create an OpenGL context.
• npix: A pointer to an integer where the number of matching pixel formats will be stored. If the function call is successful, this integer will be greater than 0, indicating the number of matching pixel formats that were found.

Returns: A CGLError value indicating whether the function call was successful or not. If the function call was successful, it will return kCGLNoError. If there was an error, it will return a different error code indicating the nature of the error.

describePixelFormat

protected int describePixelFormat(MemorySegment pixelFormat,
 int attribute,
 int pixNum)

Retrieve a pixel format value for a given attribute. Signature of CGLDescribePixelFormat used in this implementation :

• pix: A CGLPixelFormatObj object representing the pixel format that you want to describe. You can obtain a pixel format object by calling CGLChoosePixelFormat or CGLCreateContext.
• attrib: An integer representing the attribute that you want to query. This can be one of many attributes, such as the number of color bits, the number of depth bits, or the number of stencil bits. You can find a full list of pixel format attributes in the CGLPixelFormat.h header file.
• value: A pointer to an integer where the value of the queried attribute will be stored.

Returns: A CGLError value indicating whether the function call was successful or not. If the function call was successful, it will return kCGLNoError. If there was an error, it will return a different error code indicating the nature of the error.

Parameters:

attribute - the ID of the attribute we want to check

length - MAYBE!! The number of elements int pixel format array

Returns:

the attribute value

throwExceptionUponError

protected void throwExceptionUponError(String info,
 int status)

Check the status returned by CGL invocation and throw a runtime exception if not success