[skip-ci] improve SetFillColorAlpha documentation (root-project#14606)

* [skip-ci] improve SetFillColorAlpha documentation

In the top example, one might think that 0.35 was the degree of transparency rather than the degree of opacity.

* [skip-ci] amend other occurences of alpha as opacity in docu

core/base/src/TAttFill.cxx

@@ -55,8 +55,8 @@ End_Macro
 ### Color transparency
 `SetFillColorAlpha()`, allows to set a transparent color.
 In the following example the fill color of the histogram `histo`
-is set to blue with a transparency of 35%. The color `kBlue`
-itself remains fully opaque.
+is set to blue with an opacity of 35% (i.e. a transparency of 65%).
+(The color `kBlue` itself is internally stored as fully opaque.)
 
 ~~~ {.cpp}
 histo->SetFillColorAlpha(kBlue, 0.35);
@@ -67,6 +67,9 @@ The transparency is available on all platforms when the flag
 with the Cocoa backend.
 On the file output it is visible with PDF, PNG, Gif, JPEG, SVG, TeX... but not PostScript.
 
+Alternatively, you can call at the top of your script `gSytle->SetCanvasPreferGL();`.
+Or if you prefer to activate GL for a single canvas `c`, then use `c->SetSupportGL(true);`.
+
 ### The ROOT Color Wheel.
 The wheel contains the recommended 216 colors to be used in web applications.
 The colors in the Color Wheel are created by TColor::CreateColorWheel.
@@ -255,8 +258,10 @@ void TAttFill::SetFillAttributes()
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Set a transparent fill color. falpha defines the percentage of
-/// the color opacity from 0. (fully transparent) to 1. (fully opaque).
+/// Set a transparent fill color. 
+/// \param fcolor defines the fill color
+/// \param falpha defines the percentage of opacity from 0. (fully transparent) to 1. (fully opaque).
+/// \note falpha is ignored (treated as 1) if the TCanvas has no GL support activated.
 
 void TAttFill::SetFillColorAlpha(Color_t fcolor, Float_t falpha)
 {

core/base/src/TAttLine.cxx

@@ -57,8 +57,8 @@ End_Macro
 ### Color transparency
 `SetLineColorAlpha()`, allows to set a transparent color.
 In the following example the line color of the histogram `histo`
-is set to blue with a transparency of 35%. The color `kBlue`
-itself remains fully opaque.
+is set to blue with an opacity of 35% (i.e. a transparency of 65%).
+(The color `kBlue` itself is internally stored as fully opaque.)
 
 ~~~ {.cpp}
 histo->SetLineColorAlpha(kBlue, 0.35);
@@ -68,6 +68,8 @@ The transparency is available on all platforms when the flag `OpenGL.CanvasPrefe
 in `$ROOTSYS/etc/system.rootrc`, or on Mac with the Cocoa backend. On the file output
 it is visible with PDF, PNG, Gif, JPEG, SVG, TeX ... but not PostScript.
 
+Alternatively, you can call at the top of your script `gSytle->SetCanvasPreferGL();`.
+Or if you prefer to activate GL for a single canvas `c`, then use `c->SetSupportGL(true);`.
 
 \anchor ATTLINE2
 ## Line Width
@@ -295,8 +297,10 @@ void TAttLine::SetLineAttributes()
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Set a transparent line color. lalpha defines the percentage of
-/// the color opacity from 0. (fully transparent) to 1. (fully opaque).
+/// Set a transparent line color. 
+/// \param lcolor defines the line color
+/// \param lalpha defines the percentage of opacity from 0. (fully transparent) to 1. (fully opaque).
+/// \note lalpha is ignored (treated as 1) if the TCanvas has no GL support activated.
 
 void TAttLine::SetLineColorAlpha(Color_t lcolor, Float_t lalpha)
 {

core/base/src/TAttMarker.cxx

@@ -59,8 +59,8 @@ End_Macro
 
 `SetMarkerColorAlpha()`, allows to set a transparent color.
 In the following example the marker color of the histogram `histo`
-is set to blue with a transparency of 35%. The color `kBlue`
-itself remains fully opaque.
+is set to blue with an opacity of 35% (i.e. a transparency of 65%).
+(The color `kBlue` itself is internally stored as fully opaque.)
 
 ~~~ {.cpp}
 histo->SetMarkerColorAlpha(kBlue, 0.35);
@@ -70,6 +70,9 @@ The transparency is available on all platforms when the flag `OpenGL.CanvasPrefe
 in `$ROOTSYS/etc/system.rootrc`, or on Mac with the Cocoa backend. On the file output
 it is visible with PDF, PNG, Gif, JPEG, SVG, TeX ... but not PostScript.
 
+Alternatively, you can call at the top of your script `gSytle->SetCanvasPreferGL();`.
+Or if you prefer to activate GL for a single canvas `c`, then use `c->SetSupportGL(true);`.
+
 \anchor ATTMARKER2
 ## Marker style
 
@@ -367,8 +370,10 @@ void TAttMarker::SetMarkerAttributes()
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Set a transparent marker color. malpha defines the percentage of
-/// the color opacity from 0. (fully transparent) to 1. (fully opaque).
+/// Set a transparent marker color. 
+/// \param mcolor defines the marker color
+/// \param malpha defines the percentage of opacity from 0. (fully transparent) to 1. (fully opaque).
+/// \note malpha is ignored (treated as 1) if the TCanvas has no GL support activated.
 
 void TAttMarker::SetMarkerColorAlpha(Color_t mcolor, Float_t malpha)
 {

core/base/src/TAttText.cxx

@@ -127,8 +127,8 @@ End_Macro
 ### Color transparency
 `SetTextColorAlpha()`, allows to set a transparent color.
 In the following example the text color of the text `text`
-is set to blue with a transparency of 35%. The color `kBlue`
-itself remains fully opaque.
+is set to blue with an opacity of 35% (i.e. a transparency of 65%).
+(The color `kBlue` itself is internally stored as fully opaque.)
 
 ~~~ {.cpp}
 text->SetTextColorAlpha(kBlue, 0.35);
@@ -138,6 +138,9 @@ The transparency is available on all platforms when the flag `OpenGL.CanvasPrefe
 in `$ROOTSYS/etc/system.rootrc`, or on Mac with the Cocoa backend. On the file output
 it is visible with PDF, PNG, Gif, JPEG, SVG, TeX ... but not PostScript.
 
+Alternatively, you can call at the top of your script `gSytle->SetCanvasPreferGL();`.
+Or if you prefer to activate GL for a single canvas `c`, then use `c->SetSupportGL(true);`.
+
 \anchor ATTTEXT4
 ## Text Size
 
@@ -402,8 +405,10 @@ void TAttText::SetTextAttributes()
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Set a transparent marker color. talpha defines the percentage of
-/// the color opacity from 0. (fully transparent) to 1. (fully opaque).
+/// Set a transparent text color. 
+/// \param tcolor defines the text color
+/// \param talpha defines the percentage of opacity from 0. (fully transparent) to 1. (fully opaque).
+/// \note talpha is ignored (treated as 1) if the TCanvas has no GL support activated.
 
 void TAttText::SetTextColorAlpha(Color_t tcolor, Float_t talpha)
 {

core/base/src/TColor.cxx

@@ -1005,8 +1005,8 @@ in parallelcoordtrans.C.
 To ease the creation of a transparent color the static method
 `GetColorTransparent(Int_t color, Float_t a)` is provided.
 In the following example the `trans_red` color index point to
-a red color 30% transparent. The alpha value of the color index
-`kRed` is not modified.
+a red color 30% opaque (70% transparent). The alpha value of
+the color index `kRed` is not modified.
 
 ~~~ {.cpp}
  Int_t trans_red = GetColorTransparent(kRed, 0.3);
@@ -1016,8 +1016,8 @@ This function is also used in the methods
 `SetFillColorAlpha()`, `SetLineColorAlpha()`,
 `SetMarkerColorAlpha()` and `SetTextColorAlpha()`.
 In the following example the fill color of the histogram `histo`
-is set to blue with a transparency of 35%. The color `kBlue`
-itself remains fully opaque.
+is set to blue with an opacity of 35% (i.e. a transparency of 65%).
+(The color `kBlue` itself is internally stored as fully opaque.)
 
 ~~~ {.cpp}
  histo->SetFillColorAlpha(kBlue, 0.35);
@@ -1026,6 +1026,10 @@ itself remains fully opaque.
 The transparency is available on all platforms when the flag `OpenGL.CanvasPreferGL` is set to `1`
 in `$ROOTSYS/etc/system.rootrc`, or on Mac with the Cocoa backend. On the file output
 it is visible with PDF, PNG, Gif, JPEG, SVG, TeX ... but not PostScript.
+
+Alternatively, you can call at the top of your script `gSytle->SetCanvasPreferGL();`.
+Or if you prefer to activate GL for a single canvas `c`, then use `c->SetSupportGL(true);`.
+
 The following macro gives an example of transparency usage:
 
 Begin_Macro(source)
@@ -2046,7 +2050,7 @@ Int_t TColor::GetColorDark(Int_t n)
 
 ////////////////////////////////////////////////////////////////////////////////
 /// Static function: Returns the transparent color number corresponding to n.
-/// The transparency level is given by the alpha value a. If a color with the same
+/// The opacity level is given by the alpha value a. If a color with the same
 /// RGBa values already exists it is returned.
 
 Int_t TColor::GetColorTransparent(Int_t n, Float_t a)
@@ -2433,7 +2437,7 @@ void TColor::SetGrayscale(Bool_t set /*= kTRUE*/)
 /// \param fileName: Name of a .txt file (ASCII) containing three floats per
 /// line, separated by spaces, namely the r g b fractions of the color, each
 /// value being in the range [0,1].
-/// \param alpha the global transparency for all colors within this palette
+/// \param alpha the global opacity for all colors within this palette
 /// \return a positive value on success and -1 on error.
 /// \author Fernando Hueso-González
 Int_t TColor::CreateColorTableFromFile(TString fileName, Float_t alpha)