% \iffalse meta-comment
%
%% File: l3opacity.dtx
%
% Copyright (C) 2021-2026 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    http://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3opacity} module\\ Opacity (transparency) support^^A
% }
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2026-02-18}
%
% \maketitle
%
% \begin{documentation}
%
% \section{Selecting opacity}
%
% Opacity (transparency) shares many characteristics with color. However,
% limitations in terms of backends mean that it is not always possible
% to use a dedicated stack for tracking opacity. The best results when
% breaking pages are therefore likely to result using direct PDF output
% (\pdfTeX{}, \LuaTeX{}).
%
% For users of PostScript-based routes, note that there are security
% restrictions which can prevent opacity being available in output. In
% particular, using Adobe Distiller, you will need to enable transparency
% in the (text-based) configuration: this is not selectable from the GUI.
%
% For users of PDF-based routes, note that opacity only takes effect if
% |\RequirePackage{pdfmanagement}| or \cs{DocumentMetadata}|{}| is
% added \emph{before} \cs[no-index]{documentclass}, which loads and activates
% the PDF management.
% See \file{pdfmanagement-testphase.pdf} for more info.
%
% \begin{function}[added = 2025-03-27]
%   {\opacity_select:n, \opacity_fill:n, \opacity_stroke:n}
%   \begin{syntax}
%     \cs{opacity_select:n} \Arg{expression}
%   \end{syntax}
%   Evaluates the \meta{expression}, which should yield a value in the
%   range~$[0,1]$. This is then activated as an opacity for all cases
%   (\texttt{select}) or selectivity (\texttt{fill} and \texttt{stroke}).
%   The scope of the opacity setting is limited to the current \TeX{} group.
% \end{function}
%
% \begin{function}[added = 2026-01-14]
%   {
%     \opacity_begin:n        ,
%     \opacity_fill_begin:n   ,
%     \opacity_stroke_begin:n ,
%     \opacity_end:           ,
%     \opacity_fill_end:      ,
%     \opacity_stroke_end:
%   }
%   \begin{syntax}
%     \cs{opacity_begin:n} \Arg{expression}
%       \meta{content}
%     \cs{opacity_end:}
%   \end{syntax}
%   Evaluates the \meta{expression} and activates opacity for all cases
%   (\texttt{begin}) or selectivity (\texttt{fill} and \texttt{stroke}).
%   Each \texttt{begin} must have a matching \texttt{end}, but these may occur
%   at \emph{different} group levels.
%   \begin{texnote}
%     These functions do \emph{not} create a \TeX{} group, so can be split
%     for example across \tn{halign} cells.
%   \end{texnote}
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3opacity} implementation}
%
%    \begin{macrocode}
%<*code>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=opacity>
%    \end{macrocode}
%
% Transitional support.
%    \begin{macrocode}
\cs_if_exist:NT \@expl@finalise@setup@@@@
  {
    \tl_gput_right:Nn \@expl@finalise@setup@@@@
      { \declare@file@substitution { l3opacity.sty } { null.tex } }
  }
%    \end{macrocode}
%
% \begin{variable}{\l_@@_tmp_fp}
%   Temporary storage.
%    \begin{macrocode}
\fp_new:N \l_@@_tmp_fp
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\opacity_select:n, \opacity_fill:n, \opacity_stroke:n}
% \begin{macro}
%   {\opacity_begin:n, \opacity_fill_begin:n, \opacity_stroke_begin:n}
% \begin{macro}{\opacity_end:, \opacity_fill_end:, \opacity_stroke_end:}
% \begin{macro}{\@@_select:nNn}
% \begin{macro}{\@@_select:nN}
%   Thin wrapper with error checking. Opacity is passed to backend
% functions as a bounded, evaluated decimal number.
%    \begin{macrocode}
\cs_new_protected:Npn \opacity_select:n #1
  {
    \@@_select:nNn {#1} \@@_backend_select:n
      { \group_insert_after:N \@@_backend_reset: }
  }
\cs_new_protected:Npn \opacity_fill:n #1
  {
    \@@_select:nNn {#1} \@@_backend_fill:n
      { \group_insert_after:N \@@_backend_reset_fill: }
  }
\cs_new_protected:Npn \opacity_stroke:n #1
  {
    \@@_select:nNn {#1} \@@_backend_stroke:n
      { \group_insert_after:N \@@_backend_reset_stroke: }
  }
\cs_new_protected:Npn \opacity_begin:n #1
  { \@@_select:nN {#1} \@@_backend_select:n }
\cs_new_protected:Npn \opacity_fill_begin:n #1
  { \@@_select:nN {#1} \@@_backend_fill:n }
\cs_new_protected:Npn \opacity_stroke_begin:n #1
  { \@@_select:nN {#1} \@@_backend_stroke:n }
\cs_new_protected:Npn \opacity_end:
  { \@@_backend_reset: }
\cs_new_protected:Npn \opacity_fill_end:
  { \@@_backend_reset_fill: }
\cs_new_protected:Npn \opacity_stroke_end:
  { \@@_backend_reset_stroke: }
\cs_new_protected:Npn \@@_select:nNn #1#2#3
  {
    \fp_set:Nn \l_@@_tmp_fp {#1}
    \bool_lazy_or:nnTF
      { \fp_compare_p:nNn \l_@@_tmp_fp < \c_zero_fp }
      { \fp_compare_p:nNn \l_@@_tmp_fp > \c_one_fp }
      { \msg_error:nnn { opacity } { out-of-range } {#1} }
      {
        \exp_args:Ne #2 { \fp_use:N \l_@@_tmp_fp }
        #3
      }
  }
\cs_new_protected:Npn \@@_select:nN #1#2
  { \@@_select:nNn {#1} #2 { } }
\msg_new:nnnn { opacity } { out-of-range }
  { Opacity~value~out~of~range. }
  {
    LaTeX~was~asked~to~set~opacity~of~#1,~but~only~values~in~the~range~
    0~to~1~are~supported.
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%    \begin{macrocode}
%</code>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex