% \iffalse meta-comment
%
%% File: l3draw-scopes.dtx
%
% Copyright (C) 2018-2024 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 "l3experimental 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>
\RequirePackage{expl3}
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3draw} package\\ Drawing scopes^^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 2024-03-14}
%
% \maketitle
%
% \begin{implementation}
%
% \section{\pkg{l3draw-scopes} implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=draw>
%    \end{macrocode}
%
% This sub-module covers more-or-less the same ideas as
% \texttt{pgfcorescopes.code.tex}. At present, equivalents of the
% following are currently absent:
% \begin{itemize}
%   \item \cs{pgftext}: This is covered at this level by the coffin-based
%     interface \cs{draw_coffin_use:Nnn}
% \end{itemize}
%
% \subsection{Drawing environment}
%
% \begin{variable}
%   {\g_@@_xmax_dim, \g_@@_xmin_dim, \g_@@_ymax_dim, \g_@@_ymin_dim}
%   Used to track the overall (official) size of the image created: may
%   not actually be the natural size of the content.
%    \begin{macrocode}
\dim_new:N \g_@@_xmax_dim
\dim_new:N \g_@@_xmin_dim
\dim_new:N \g_@@_ymax_dim
\dim_new:N \g_@@_ymin_dim
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_draw_bb_update_bool}
%   Flag to indicate that a path (or similar) should update the bounding box
%   of the drawing.
%    \begin{macrocode}
\bool_new:N \l_draw_bb_update_bool
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_layer_main_box, \l_@@_layer_main_box}
%   Box for setting the drawing itself and the top-level layer.
%    \begin{macrocode}
\box_new:N \l_@@_main_box
\box_new:N \l_@@_layer_main_box
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_id_int}
%   The drawing number.
%    \begin{macrocode}
\int_new:N \g_@@_id_int
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\@@_reset_bb:}
%   A simple auxiliary.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_reset_bb:
  {
    \dim_gset:Nn \g_@@_xmax_dim { -\c_max_dim }
    \dim_gset:Nn \g_@@_xmin_dim {  \c_max_dim }
    \dim_gset:Nn \g_@@_ymax_dim { -\c_max_dim }
    \dim_gset:Nn \g_@@_ymin_dim {  \c_max_dim }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\draw_begin:, \draw_end:}
%   Drawings are created by setting them into a box, then adjusting the box
%   before inserting into the surroundings. Color is set here using the drawing
%   mechanism largely as it then sets up the internal data structures. It may be
%   that a coffin construct is better here in the longer term: that may become
%   clearer as the code is completed. As we need to avoid any insertion of
%   baseline skips, the outer box here has to be an |hbox|. To allow for
%   layers, there is some box nesting: notice that we 
%    \begin{macrocode}
\cs_new_protected:Npn \draw_begin:
  {
    \group_begin:
      \int_gincr:N \g_@@_id_int
      \hbox_set:Nw \l_@@_main_box
        \@@_backend_begin:
        \@@_reset_bb:
        \@@_path_reset_limits:
        \bool_set_true:N \l_draw_bb_update_bool
        \draw_transform_matrix_reset:
        \draw_transform_shift_reset:
        \@@_softpath_clear:
        \draw_linewidth:n { \l_draw_default_linewidth_dim }
        \color_select:n { . }
        \draw_nonzero_rule:
        \draw_cap_butt:
        \draw_join_miter:
        \draw_miterlimit:n { 10 }
        \draw_dash_pattern:nn { } { 0cm }
        \hbox_set:Nw \l_@@_layer_main_box
  }
\cs_new_protected:Npn \draw_end:
  {
          \@@_baseline_finalise:w
          \exp_args:NNNV \hbox_set_end:
          \clist_set:Nn \l_draw_layers_clist \l_draw_layers_clist
          \@@_layers_insert:
        \@@_backend_end:
      \hbox_set_end:
      \dim_compare:nNnT \g_@@_xmin_dim = \c_max_dim
        {
          \dim_gzero:N \g_@@_xmax_dim
          \dim_gzero:N \g_@@_xmin_dim
          \dim_gzero:N \g_@@_ymax_dim
          \dim_gzero:N \g_@@_ymin_dim
        }
      \@@_finalise:
      \box_set_wd:Nn \l_@@_main_box
        { \g_@@_xmax_dim - \g_@@_xmin_dim }
      \mode_leave_vertical:
      \box_use_drop:N \l_@@_main_box
    \group_end:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_finalise:}
% \begin{macro}{\@@_finalise_baseline:n}
%   Finalising the (vertical) size of the output depends on whether we have
%   an explicit baseline or not. To allow for that, we have two functions, and
%   the one that's used depends on whether the user has set a baseline. Notice
%   that in contrast to \pkg{pgf} we \emph{do} allow for a non-zero depth if
%   the explicit baseline is above the lowest edge of the initial bounding box.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_finalise:
  {
    \hbox_set:Nn \l_@@_main_box
      {
        \skip_horizontal:n { -\g_@@_xmin_dim }
        \box_move_down:nn
          { \g_@@_ymin_dim }
          { \box_use_drop:N \l_@@_main_box }
      }
    \box_set_dp:Nn \l_@@_main_box { 0pt }
    \box_set_ht:Nn \l_@@_main_box
      { \g_@@_ymax_dim - \g_@@_ymin_dim }
  }
\cs_new_protected:Npn \@@_finalise_baseline:n #1
  {
    \hbox_set:Nn \l_@@_main_box
      {
        \skip_horizontal:n { -\g_@@_xmin_dim }
        \box_move_down:nn
          {#1}
          { \box_use_drop:N \l_@@_main_box }
      }
    \box_set_dp:Nn \l_@@_main_box
      {
        \dim_max:nn
          { #1 - \g_@@_ymin_dim }
          { 0pt }
      }
    \box_set_ht:Nn \l_@@_main_box
      { \g_@@_ymax_dim - #1 }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Baseline position}
%
% \begin{variable}{\l_@@_baseline_bool, \l_@@_baseline_dim}
%   For tracking the explicit baseline and whether it is active.
%    \begin{macrocode}
\bool_new:N \l_@@_baseline_bool
\dim_new:N \l_@@_baseline_dim
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\draw_baseline:n}
%   A simple setting of the baseline along with the flag we need to know that
%   it is active.
%    \begin{macrocode}
\cs_new_protected:Npn \draw_baseline:n #1
  {
    \bool_set_true:N \l_@@_baseline_bool
    \dim_set:Nn \l_@@_baseline_dim { \fp_to_dim:n {#1} }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_baseline_finalise:w}
%   Rather than use a global data structure, we can arrange to put the baseline
%   value at the right group level with a small amount of shuffling. That happens
%   here.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_baseline_finalise:w #1 \@@_finalise:
  {
    \bool_if:NTF \l_@@_baseline_bool
      {
        \use:e
          {
            \exp_not:n {#1}
            \@@_finalise_baseline:n { \dim_use:N \l_@@_baseline_dim }
          }
      }
      { #1 \@@_finalise: }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Scopes}
%
% \begin{variable}{\l_@@_linewidth_dim}
% \begin{variable}{\l_@@_fill_color_tl, \l_@@_stroke_color_tl}
%   Storage for local variables.
%    \begin{macrocode}
\dim_new:N \l_@@_linewidth_dim
\tl_new:N \l_@@_fill_color_tl
\tl_new:N \l_@@_stroke_color_tl
%    \end{macrocode}
% \end{variable}
% \end{variable}
%
% \begin{macro}{\draw_scope_begin:, \draw_scope_begin:}
%   As well as the graphics (and \TeX{}) scope, also deal with global
%   data structures.
%    \begin{macrocode}
\cs_new_protected:Npn \draw_scope_begin:
  {
    \@@_backend_scope_begin:
    \group_begin:
      \dim_set_eq:NN \l_@@_linewidth_dim \g_@@_linewidth_dim
      \draw_path_scope_begin:
  }
\cs_new_protected:Npn \draw_scope_end:
  {
      \draw_path_scope_end:
      \dim_gset_eq:NN \g_@@_linewidth_dim \l_@@_linewidth_dim
    \group_end:
    \@@_backend_scope_end:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}
%   {\l_@@_xmax_dim, \l_@@_xmin_dim, \l_@@_ymax_dim, \l_@@_ymin_dim}
%   Storage for the bounding box.
%    \begin{macrocode}
\dim_new:N \l_@@_xmax_dim
\dim_new:N \l_@@_xmin_dim
\dim_new:N \l_@@_ymax_dim
\dim_new:N \l_@@_ymin_dim
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\@@_scope_bb_begin:, \@@_scope_bb_end:}
%   The bounding box is simple: a straight group-based save and restore
%   approach.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_scope_bb_begin:
  {
    \group_begin:
      \dim_set_eq:NN \l_@@_xmax_dim \g_@@_xmax_dim
      \dim_set_eq:NN \l_@@_xmin_dim \g_@@_xmin_dim
      \dim_set_eq:NN \l_@@_ymax_dim \g_@@_ymax_dim
      \dim_set_eq:NN \l_@@_ymin_dim \g_@@_ymin_dim
      \@@_reset_bb:
  }
\cs_new_protected:Npn \@@_scope_bb_end:
  {
      \dim_gset_eq:NN \g_@@_xmax_dim \l_@@_xmax_dim
      \dim_gset_eq:NN \g_@@_xmin_dim \l_@@_xmin_dim
      \dim_gset_eq:NN \g_@@_ymax_dim \l_@@_ymax_dim
      \dim_gset_eq:NN \g_@@_ymin_dim \l_@@_ymin_dim
    \group_end:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\draw_suspend_begin:, \draw_suspend_end:}
%   Suspend all parts of a drawing.
%    \begin{macrocode}
\cs_new_protected:Npn \draw_suspend_begin:
  {
    \@@_scope_bb_begin:
    \draw_path_scope_begin:
    \draw_transform_matrix_reset:
    \draw_transform_shift_reset:
    \@@_layers_save:
  }
\cs_new_protected:Npn \draw_suspend_end:
  {
    \@@_layers_restore:
    \draw_path_scope_end:
    \@@_scope_bb_end:
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex