The default behavior is that GL surfaces are on top of all non-GL content in
the window. This maximizes the performance for the common case of games, but
clipping by parents, siblings, and child windows isn't respected.
Setting OpenGLSurfaceMode to "behind" pushes the GL surface to be behind the
Mac window. The window has transparent holes punched through it so that the GL
surface shows through. USER32 and the wineserver take care of making sure the
holes are only where the GL windows would be unclipped and unoccluded. Because
the OS X window server has to composite the GL surface with the window, this
limits the framerate.
Since the Mac driver has no server-side rendering path, GDI rendering to a
window which has a GL surface doesn't work. As a partial workaround, mostly
for cases where a GL surface is created but never used, setting
OpenGLSurfaceMode to "transparent" allows the GDI rendering to show through the
transparent parts of the GL surface. The GDI rendering is drawn to the
top-level window's surface as normal. (The behavior of user32 to exclude the
portion covered by a GL window from GDI rendering is disabled.) The GL surface
is in front of the window but potentially wholly or partially transparent. It
is composited with the window behind it.
The GL surface is initially cleared to be completely transparent. So, if
no GL rendering is done, the window will appear as though the GL surface didn't
exist.
47708c2635