Debian Codegraph @

README-LegacyOpenGLState

raw
1 TL/DR: Skip to "WORK-AROUND".
2
3 PROBLEM
4 =======
5
6 Unfortunately, FTGL has contained two strictly incompatible
7 behaviours for a long time:
8
9 The initial library set some OpenGL state, e.g. glEnable(GL_BLEND)
10 and glBlendFunc(), from the rendering functions. Not only may this
11 not be what the user wants, the blending function used is also not
12 quite correct. See
13 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=742469) for a
14 detailed explanation and example.
15
16 A fix made by sammy in 2009, see
17 https://github.com/frankheckenbach/ftgl/commit/29603ae3fa88c5b9e079a6db23be2cdea95aef39
18 removed these settings, but it was never picked up by Debian and
19 possibly other distributions.
20
21 As a result, programs assuming the new behaviour would behave
22 wrongly without the fix. This cannot be changed from within those
23 programs, i.e. outside of the library, because the library without
24 the fix would override the settings.
25
26 OTOH, programs built against the original version would assume these
27 settings and not render correctly with the fix applied. These could
28 be fixed in principle by making the settings from within the
29 programs, but after almost 10 years of ignoring the problem, some of
30 those programs have apparently become unmaintained, or maintained
31 just to the bare minimum, so expecting them all to fix the issue
32 seems unrealistic.
33
34 So as a kludge, version 2.4 of FTGL adds a new flag to choose the
35 behaviour, as described under "WORK-AROUND" (not a real solution,
36 but the best we can realistically get).
37
38 To avoid mismatch between the two behaviours, the library will only
39 allow to set this flag to the same value (but any number of times)
40 within one program run. So, e.g. if your code includes some
41 libraries that in turn use FTGL, and they all set this flag to
42 false, all is fine. But if some of them set it to false, and some to
43 true, things can't work, as described above. To avoid confusion, on
44 an attempt to set the flag to a different value than was set before,
45 FTGL will throw an exception (a std::logic_error which should not be
46 caught in general usually, neither here in particular).
47
48
49 WORK-AROUND
50 ===========
51
52 The handling of OpenGL state should now be set with
53
54 FTLibrary::Instance().LegacyOpenGLState(On);
55
56 You should add a call to this function near the start of all your
57 programs that use FTGL, and in some strategic place in all libraries
58 that use FTGL.
59
60 If your code relies on FTGL automatically setting some OpenGL state,
61 like the versions in Debian and possibly other distributions do,
62 pass "true" for the "On" parameter. If you don't call
63 LegacyOpenGLState, this is the default behaviour for now, but in the
64 future, FTGL will warn about it and finally fail.
65
66 If you need manual control over the OpenGL state, like the versions
67 on GitHub do, pass "false".
68
69 Even if you use the legacy version ("true"), you might want to
70 consider changing to manual setting ("false"). To retain the old
71 behaviour then, make the following OpenGL calls from your code,
72 either globally, or before each respective rendering, possibly
73 protected with glPushAttrib/glPopAttrib:
74
75 glEnable(GL_BLEND);
76 glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
77
78 To get a better rendering function, instead add:
79
80 #define GL_GLEXT_PROTOTYPES
81
82 before including OpenGL headers, and then do:
83
84 glEnable(GL_BLEND);
85 glBlendFuncSeparate(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA,
86 GL_ONE, GL_ONE_MINUS_SRC_ALPHA);