From 0c69c481816c25986c17b5755404d7dbca21b478 Mon Sep 17 00:00:00 2001 From: Hin-Tak Leung Date: Sat, 1 Jun 2024 07:13:40 +0100 Subject: [PATCH] Adding references and code snipplets to OpenGL settings for Apple users fixes #214 --- docs/tutorial/canvas.rst | 10 ++++++++++ relnotes/README.m116.md | 30 ++++++++++++++++++++++++++++++ tests/conftest.py | 5 +++++ 3 files changed, 45 insertions(+) diff --git a/docs/tutorial/canvas.rst b/docs/tutorial/canvas.rst index 995e25b3..16eb1791 100644 --- a/docs/tutorial/canvas.rst +++ b/docs/tutorial/canvas.rst @@ -90,6 +90,11 @@ The following example uses glfw package to create an OpenGL context. Install raise RuntimeError('glfw.init() failed') glfw.window_hint(glfw.VISIBLE, glfw.FALSE) glfw.window_hint(glfw.STENCIL_BITS, 8) + # see https://www.glfw.org/faq#macos + glfw.window_hint(glfw.CONTEXT_VERSION_MAJOR, 3) + glfw.window_hint(glfw.CONTEXT_VERSION_MINOR, 2) + glfw.window_hint(glfw.OPENGL_FORWARD_COMPAT, True) + glfw.window_hint(glfw.OPENGL_PROFILE, glfw.OPENGL_CORE_PROFILE) window = glfw.create_window(640, 480, '', None, None) glfw.make_context_current(window) yield window @@ -138,6 +143,11 @@ Here's a complete example: if not glfw.init(): raise RuntimeError('glfw.init() failed') glfw.window_hint(glfw.STENCIL_BITS, 8) + # see https://www.glfw.org/faq#macos + glfw.window_hint(glfw.CONTEXT_VERSION_MAJOR, 3) + glfw.window_hint(glfw.CONTEXT_VERSION_MINOR, 2) + glfw.window_hint(glfw.OPENGL_FORWARD_COMPAT, True) + glfw.window_hint(glfw.OPENGL_PROFILE, glfw.OPENGL_CORE_PROFILE) window = glfw.create_window(WIDTH, HEIGHT, '', None, None) glfw.make_context_current(window) yield window diff --git a/relnotes/README.m116.md b/relnotes/README.m116.md index 78b5a237..a4a16c5d 100644 --- a/relnotes/README.m116.md +++ b/relnotes/README.m116.md @@ -21,6 +21,9 @@ of this update had taken from. * TL;DR - `m87` users would likely find most existing python scripts work. Some routines need a new `skia.SamplingOptions()` argument, or switch from `skia.FilterQuality` to `skia.SamplingOptions()`. + OpenGL users, especially on Apple Mac OS, may now need to specify + a compatible OpenGL profile for their GPU hardware/software combination + to avoid shader-compilation related errors (See more about this below). Please report `AttributeError: 'skia.AAA' object has no attribute 'BBB'` errors, to prioritize fixing remaining differences between `m87` and `m116`. @@ -38,6 +41,33 @@ of this update had taken from. are removed/disabled when there are no obvious new-equivalents, or not-too-troblesome emulations with `m116`. The "AttributeError" error mentioned above. +* Be **WARN**'ed on OpenGL usage: Google folks added subtantial GPU/driver + detection code in upsteam Skia between m87 and m116, to optimize for speed and + work-around driver bugs. If you use a non-open-source GPU driver, i.e. + everybody except Mesa on Linux, and especially Apple Mac users, + you may need to request compatible OpenGL profile to match the your + GPU/driver's capability. For Apple Mac users, with `glfw`, adds the following: + +``` +# see https://www.glfw.org/faq#macos +glfw.window_hint(glfw.CONTEXT_VERSION_MAJOR, 3) +glfw.window_hint(glfw.CONTEXT_VERSION_MINOR, 2) +glfw.window_hint(glfw.OPENGL_FORWARD_COMPAT, True) +glfw.window_hint(glfw.OPENGL_PROFILE, glfw.OPENGL_CORE_PROFILE) +``` + + OSX OpenGL users may need to add `GLUT_3_2_CORE_PROFILE` to their `glutInitDisplayMode()` + invocation e.g. `glutInitDisplayMode(... | GLUT_3_2_CORE_PROFILE)`. `pysdl2` users + need: + +``` +sdl2.SDL_GL_SetAttribute(sdl2.SDL_GL_CONTEXT_MAJOR_VERSION, 3) +sdl2.SDL_GL_SetAttribute(sdl2.SDL_GL_CONTEXT_MINOR_VERSION, 2) +sdl2.SDL_GL_SetAttribute(sdl2.SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG, True) +sdl2.SDL_GL_SetAttribute(sdl2.SDL_GL_CONTEXT_PROFILE_MASK, + sdl2.SDL_GL_CONTEXT_PROFILE_CORE) +``` + * Where it is possible, when `m87` APIs disappear, emulations with `m116` is done. So these are "new emulations of old APIs". While they work, they might be withdrawn/changed later: diff --git a/tests/conftest.py b/tests/conftest.py index 32f07936..a8b40518 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -15,6 +15,11 @@ def glfw_context(): raise RuntimeError('glfw.init() failed') glfw.window_hint(glfw.VISIBLE, glfw.FALSE) glfw.window_hint(glfw.STENCIL_BITS, 8) + # see https://www.glfw.org/faq#macos + glfw.window_hint(glfw.CONTEXT_VERSION_MAJOR, 3) + glfw.window_hint(glfw.CONTEXT_VERSION_MINOR, 2) + glfw.window_hint(glfw.OPENGL_FORWARD_COMPAT, True) + glfw.window_hint(glfw.OPENGL_PROFILE, glfw.OPENGL_CORE_PROFILE) context = glfw.create_window(640, 480, '', None, None) glfw.make_context_current(context) logger.debug('glfw context created')