[gentoo-dev] RFC: gles global USE flag, USE=opengl clarifying

[gentoo-dev] RFC: gles global USE flag, USE=opengl clarifying

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 7355 bytes --]

Hello,

Currently we have rather a mess in terms of OpenGL API handling.
I think much of it comes from USE=opengl being rather vague - is it
supposed to mean "Use desktop GL", "Use GLX", or "Enable OpenGL
support". All of these mean quite different things:
* desktop GL means full OpenGL API, which in turn can be either used
via GLX platform (X11 only) or EGL platform.
* GLX means GLX platform - usable only on X11; all good and same as
desktop GL in the past, but we have people wanting wayland-only now
(and YES, desktop GL via EGL platform _is_ a thing), and GLX obviously
isn't something that works in native wayland.
* GL support could mean 3D via OpenGL in general; be it OpenGL, GLESv2,
GLESv3...

To make things easier to follow, there are basically three different
concepts and potential choices to make:

* API
* Platform
* Windowing system

API is either "full desktop" OpenGL (think e.g. OpenGL 4.5), or GLES;
GLES has multiple versions, but in practice it's GLESv2 with optional
support for GLESv3 - however afaik latest mesa supports GLESv3 too
whenever GLESv2 is built.

Platform is either GLX or EGL. GLX only works in combination with "full
desktop" OpenGL; EGL can work with either.
For non-Linux there's also CGL (OSX), WGL (Windows), EAGL (iOS) and
more. Can be interesting for Gentoo Prefix.

"EGL is an interface between Khronos rendering APIs such as OpenGL ES
or OpenVG and the underlying native platform window system." - thus the
third choice with EGL platform - windowing system. This then is about
supporting a certain graphics environment with EGL (with GLX that can
be taken as just always X).
This can be for example x11, wayland, GBM (think rendering 3D directly
on top of a KMS terminal), win32, cocoa, android, vivante framebuffer
(with proprietary vivante 3D stack; not applicable to open source
etnaviv), DispmanX (RPi), etc.
This can be a choice especially for certain kind of OpenGL libraries;
one big example I know of is GStreamer GL libraries.



Anyhow, here's an initial proposal to try to sort it out via a USE=gles
global USE flag and a set of guidelines how to use it together with a
USE=opengl and other related USE flags in ebuilds:


use.desc:
opengl - Add support for desktop OpenGL (3D graphics)
gles - Add support for OpenGL ES, or prefer it over desktop OpenGL. This should usually only be enabled globally on embedded systems that do not support full desktop GL.

[How is it correct to refer to "full desktop" GL without it being
confusing with OpenGL in general?]


Guidelines:

* If package has optional GL support in general (can work with either
desktop GL or GLES when OpenGL is enabled; doesn't care which one is
there), use both opengl and gles in IUSE and enable GL support and
ebuild logic when either is enabled

* If package is fully about OpenGL (GL itself isn't optional) and
supports either desktop GL or GLES, but not both at once: IUSE="gles"
and use GLES if that is set, "full desktop" GL otherwise.

* If package is fully about OpenGL (GL itself isn't optional) and
supports either desktop GL or GLES, including both at once: IUSE="gles
+opengl" and use whichever is enabled. As GL isn't optional as a whole,
require at least one of them: REQUIRED_USE="|| ( gles opengl )".

* If package has optional OpenGL support and needs specific logic for
the chosen API: IUSE="gles opengl" or IUSE="gles +opengl", depending if
GL should be default enabled (albeit we might want to revise this via
profile level defaults flag instead?) - don't default enable gles, as
it's not a common use case and such embedded system users will have it
globally enabled anyways.
** Enable any of the GL logic only if either gles or opengl is enabled.
** If both are supported at the same time, enable whichever is chosen
by user (this could often mean also passing a generic --enable-gl
passing if either USE is set and then specifying the API to use with a
separate build flag).
** If both are not supported at the same time, set REQUIRED_USE="gles?
( !opengl )", use whichever is chosen (keeping in mind that both might
be disabled → no GL at all).

* If package needs to provide choices for the used GL platform or
windowing system, while GL itself is optional as a whole, don't forget
to keep the dependencies and other logic for the platform/WS
conditional to USE=gles and/or USE=opengl. This is usually easiest to
handle via GL_DEPS helper variable with dependencies applicable to
either and then putting it in as e.g. "opengl? ( $GL_DEPS ) gles? (
$GL_DEPS )" together with any specific ones; similar for certain needed
REQUIRED_USEs, with appropriate conditional blocks in src_configure().

* If package supports X11 via either GLX or EGL x11 windowing system,
just enable GLX via USE="opengl X" (or USE="-gles X" if no opengl in
IUSE) and EGL x11 via USE="egl X". Don't forget that "egl X" should
pull in EGL and X dependencies necessary for it only if GL as a whole
is enabled, if that is optional.

* It is OK to have certain REQUIRED_USE restrictions when applicable,
but avoid unnecessary pain via appropriate use of IUSE defaults. Also
don't forget that some restrictions might only apply if GL as a whole
is enabled — e.g. REQUIRED_USE="gles? ( $GL_REQUIRED_USE ) opengl? (
$GL_REQUIRED_USE )". Don't force users to make choices when that choice
isn't even relevant — e.g. REQUIRED_USE="wayland? ( egl )", when this
is only relevant if optional GL is enable via either USE="opengl" or
USE="gles" - user would have to potentially enable egl without reason,
because he wanted non-GL wayland support for the package, but wayland
windowing system support isn't built anyways (just generic wayland
support).

----

Initially I thought of a global USE=gles2, but during the writing of
this e-mail, I realized that as USE=opengl doesn't specify a version
either (e.g. 3.3 or 4.5), so combined with gles3 not really needing a
separate handling, it'd be more consistent with just USE=gles.
However I'm rather torn on this - it could just as well be USE=gles2
instead, which just specifies that it's GLESv2 or later; then it's also
clear we don't deal with old GLESv1 via this.

I doubt this proposal is perfect, but I think it does bring a bit of
sanity and consistency to the situation. Additionally I only have a
view of what my co-maintained packages are doing, support and need; I
might not have thought of valid setups needed by other packages, which
this wouldn't work for.

I also realize this can be complex to handle by maintainers in ebuilds,
but the goal is to have it consistent and understandable to users, and 
easier to handle via global USE choice:
"If you want to enable OpenGL when it's a choice → enable USE=opengl or
USE=gles globally, depending if you have full desktop OpenGL support or
not (embedded)".

For ebuild complexity, it's not all that bad; see for example media-
libs/gst-plugins-base-1.14.1 or newer.


I'm happy to hear valid concerns where this wouldn't work or situations
where this isn't good for global choosing by user. But please be
considerate and bring up only new cases, not those that are already
brought up on the thread (that is, read all unread mails in thread
before posting yourself).


Mart

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] RFC: gles global USE flag, USE=opengl clarifying

[James Le Cuirot]

[-- Attachment #1: Type: text/plain, Size: 445 bytes --]

On Mon, 23 Jul 2018 20:11:37 +0300
Mart Raudsepp <leio@gentoo.org> wrote:

> Currently we have rather a mess in terms of OpenGL API handling.
>  ...
> Guidelines:
> ...

Thanks for discussing this with me earlier even though I don't feel I
have a large say in the matter. Having faced this mess on ARM, it can
be a little frustrating so any improvements are very welcome.

+1

-- 
James Le Cuirot (chewi)
Gentoo Linux Developer

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] RFC: gles global USE flag, USE=opengl clarifying

[Matt Turner]

On Mon, Jul 23, 2018 at 10:11 AM, Mart Raudsepp <leio@gentoo.org> wrote:
> Hello,
>
> Currently we have rather a mess in terms of OpenGL API handling.
> I think much of it comes from USE=opengl being rather vague - is it
> supposed to mean "Use desktop GL", "Use GLX", or "Enable OpenGL
> support". All of these mean quite different things:
> * desktop GL means full OpenGL API, which in turn can be either used
> via GLX platform (X11 only) or EGL platform.
> * GLX means GLX platform - usable only on X11; all good and same as
> desktop GL in the past, but we have people wanting wayland-only now
> (and YES, desktop GL via EGL platform _is_ a thing), and GLX obviously
> isn't something that works in native wayland.
> * GL support could mean 3D via OpenGL in general; be it OpenGL, GLESv2,
> GLESv3...
>
> To make things easier to follow, there are basically three different
> concepts and potential choices to make:
>
> * API
> * Platform
> * Windowing system
>
> API is either "full desktop" OpenGL (think e.g. OpenGL 4.5), or GLES;
> GLES has multiple versions, but in practice it's GLESv2 with optional
> support for GLESv3 - however afaik latest mesa supports GLESv3 too
> whenever GLESv2 is built.
>
> Platform is either GLX or EGL. GLX only works in combination with "full
> desktop" OpenGL; EGL can work with either.
> For non-Linux there's also CGL (OSX), WGL (Windows), EAGL (iOS) and
> more. Can be interesting for Gentoo Prefix.
>
> "EGL is an interface between Khronos rendering APIs such as OpenGL ES
> or OpenVG and the underlying native platform window system." - thus the
> third choice with EGL platform - windowing system. This then is about
> supporting a certain graphics environment with EGL (with GLX that can
> be taken as just always X).
> This can be for example x11, wayland, GBM (think rendering 3D directly
> on top of a KMS terminal), win32, cocoa, android, vivante framebuffer
> (with proprietary vivante 3D stack; not applicable to open source
> etnaviv), DispmanX (RPi), etc.
> This can be a choice especially for certain kind of OpenGL libraries;
> one big example I know of is GStreamer GL libraries.
>
>
>
> Anyhow, here's an initial proposal to try to sort it out via a USE=gles
> global USE flag and a set of guidelines how to use it together with a
> USE=opengl and other related USE flags in ebuilds:
>
>
> use.desc:
> opengl - Add support for desktop OpenGL (3D graphics)
> gles - Add support for OpenGL ES, or prefer it over desktop OpenGL. This should usually only be enabled globally on embedded systems that do not support full desktop GL.
>
> [How is it correct to refer to "full desktop" GL without it being
> confusing with OpenGL in general?]

That's what people on my team call it to differentiate. "Desktop" vs ES.

> Guidelines:
>
> * If package has optional GL support in general (can work with either
> desktop GL or GLES when OpenGL is enabled; doesn't care which one is
> there), use both opengl and gles in IUSE and enable GL support and
> ebuild logic when either is enabled

Sounds good.

> * If package is fully about OpenGL (GL itself isn't optional) and
> supports either desktop GL or GLES, but not both at once: IUSE="gles"
> and use GLES if that is set, "full desktop" GL otherwise.

Probably the best thing to do.

> * If package is fully about OpenGL (GL itself isn't optional) and
> supports either desktop GL or GLES, including both at once: IUSE="gles
> +opengl" and use whichever is enabled. As GL isn't optional as a whole,
> require at least one of them: REQUIRED_USE="|| ( gles opengl )".

Sounds good.

> * If package has optional OpenGL support and needs specific logic for
> the chosen API: IUSE="gles opengl" or IUSE="gles +opengl", depending if
> GL should be default enabled (albeit we might want to revise this via
> profile level defaults flag instead?) - don't default enable gles, as
> it's not a common use case and such embedded system users will have it
> globally enabled anyways.
> ** Enable any of the GL logic only if either gles or opengl is enabled.
> ** If both are supported at the same time, enable whichever is chosen
> by user (this could often mean also passing a generic --enable-gl
> passing if either USE is set and then specifying the API to use with a
> separate build flag).
> ** If both are not supported at the same time, set REQUIRED_USE="gles?
> ( !opengl )", use whichever is chosen (keeping in mind that both might
> be disabled → no GL at all).
>
> * If package needs to provide choices for the used GL platform or
> windowing system, while GL itself is optional as a whole, don't forget
> to keep the dependencies and other logic for the platform/WS
> conditional to USE=gles and/or USE=opengl. This is usually easiest to
> handle via GL_DEPS helper variable with dependencies applicable to
> either and then putting it in as e.g. "opengl? ( $GL_DEPS ) gles? (
> $GL_DEPS )" together with any specific ones; similar for certain needed
> REQUIRED_USEs, with appropriate conditional blocks in src_configure().
>
> * If package supports X11 via either GLX or EGL x11 windowing system,
> just enable GLX via USE="opengl X" (or USE="-gles X" if no opengl in
> IUSE) and EGL x11 via USE="egl X". Don't forget that "egl X" should
> pull in EGL and X dependencies necessary for it only if GL as a whole
> is enabled, if that is optional.

Sounds good.

> * It is OK to have certain REQUIRED_USE restrictions when applicable,
> but avoid unnecessary pain via appropriate use of IUSE defaults. Also
> don't forget that some restrictions might only apply if GL as a whole
> is enabled — e.g. REQUIRED_USE="gles? ( $GL_REQUIRED_USE ) opengl? (
> $GL_REQUIRED_USE )". Don't force users to make choices when that choice
> isn't even relevant — e.g. REQUIRED_USE="wayland? ( egl )", when this
> is only relevant if optional GL is enable via either USE="opengl" or
> USE="gles" - user would have to potentially enable egl without reason,
> because he wanted non-GL wayland support for the package, but wayland
> windowing system support isn't built anyways (just generic wayland
> support).
>
> ----
>
> Initially I thought of a global USE=gles2, but during the writing of
> this e-mail, I realized that as USE=opengl doesn't specify a version
> either (e.g. 3.3 or 4.5), so combined with gles3 not really needing a
> separate handling, it'd be more consistent with just USE=gles.
> However I'm rather torn on this - it could just as well be USE=gles2
> instead, which just specifies that it's GLESv2 or later; then it's also
> clear we don't deal with old GLESv1 via this.

gles2 is much more common than just gles in the tree.  There are no
known gles1 applications on desktop Linux, so I'm happy to just remove
the gles1 flag from media-libs/mesa.

I'd say we go with gles2.

> I doubt this proposal is perfect, but I think it does bring a bit of
> sanity and consistency to the situation. Additionally I only have a
> view of what my co-maintained packages are doing, support and need; I
> might not have thought of valid setups needed by other packages, which
> this wouldn't work for.
>
> I also realize this can be complex to handle by maintainers in ebuilds,
> but the goal is to have it consistent and understandable to users, and
> easier to handle via global USE choice:
> "If you want to enable OpenGL when it's a choice → enable USE=opengl or
> USE=gles globally, depending if you have full desktop OpenGL support or
> not (embedded)".
>
> For ebuild complexity, it's not all that bad; see for example media-
> libs/gst-plugins-base-1.14.1 or newer.
>
>
> I'm happy to hear valid concerns where this wouldn't work or situations
> where this isn't good for global choosing by user. But please be
> considerate and bring up only new cases, not those that are already
> brought up on the thread (that is, read all unread mails in thread
> before posting yourself).

Thanks for starting this thread (and for removing the REQUIRED_USE from gst :)

Re: [gentoo-dev] RFC: gles global USE flag, USE=opengl clarifying

[James Le Cuirot]

On Mon, 23 Jul 2018 17:43:59 -0700
Matt Turner <mattst88@gentoo.org> wrote:

> > Initially I thought of a global USE=gles2, but during the writing of
> > this e-mail, I realized that as USE=opengl doesn't specify a version
> > either (e.g. 3.3 or 4.5), so combined with gles3 not really needing
> > a separate handling, it'd be more consistent with just USE=gles.
> > However I'm rather torn on this - it could just as well be USE=gles2
> > instead, which just specifies that it's GLESv2 or later; then it's
> > also clear we don't deal with old GLESv1 via this.  
> 
> gles2 is much more common than just gles in the tree.  There are no
> known gles1 applications on desktop Linux, so I'm happy to just remove
> the gles1 flag from media-libs/mesa.
> 
> I'd say we go with gles2.

There hasn't been a new release in years but Neverball's git master
supports GLESv1! Even my Vivante-based ARM board can run it with OpenGL
though as it only requires 1.4 or something.

-- 
James Le Cuirot (chewi)
Gentoo Linux Developer