From 807dd93710d917ad3bc8c04e7f4f758b7987f29b Mon Sep 17 00:00:00 2001 From: ferdymercury Date: Wed, 7 Feb 2024 09:06:10 +0100 Subject: [PATCH] [skip-ci] improve SetFillColorAlpha documentation (#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 | 13 +++++++++---- core/base/src/TAttLine.cxx | 12 ++++++++---- core/base/src/TAttMarker.cxx | 13 +++++++++---- core/base/src/TAttText.cxx | 13 +++++++++---- core/base/src/TColor.cxx | 16 ++++++++++------ 5 files changed, 45 insertions(+), 22 deletions(-) diff --git a/core/base/src/TAttFill.cxx b/core/base/src/TAttFill.cxx index 24c5cd48fc5bb..11711c698227d 100644 --- a/core/base/src/TAttFill.cxx +++ b/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) { diff --git a/core/base/src/TAttLine.cxx b/core/base/src/TAttLine.cxx index a148176868cc5..b6dd093a2e785 100644 --- a/core/base/src/TAttLine.cxx +++ b/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) { diff --git a/core/base/src/TAttMarker.cxx b/core/base/src/TAttMarker.cxx index 58225efe2d680..1789a80bc8128 100644 --- a/core/base/src/TAttMarker.cxx +++ b/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) { diff --git a/core/base/src/TAttText.cxx b/core/base/src/TAttText.cxx index 989c2781bb289..9062dcb2da92d 100644 --- a/core/base/src/TAttText.cxx +++ b/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) { diff --git a/core/base/src/TColor.cxx b/core/base/src/TColor.cxx index 8f2df21162067..c2c7aeefdcfcd 100644 --- a/core/base/src/TColor.cxx +++ b/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)