15.3.774  src/lib/x-kit/xclient/src/window/pen-to-gcontext-imp-old.api

## pen-to-gcontext-imp-old.api
#
# To simplify the application programmer's life,
# we present an API based on immutable "pens" -- see
#
#     src/lib/x-kit/xclient/src/window/pen-old.pkg
#     src/lib/x-kit/xclient/src/window/pen-guts.api
#     src/lib/x-kit/xclient/src/window/pen-guts.pkg
#
# -- rather than the mutable graphics contexts ("gcs")
# actually implemented by the X server.  These gcs
# constitute shared mutable state, management of which
# poses a considerable challenge in a concurrent application,
# so by substituting pens for them we save the application
# programmer lots of headaches;  the penalty is that we must
# internally map pens to gcs when it comes time to actually
# execute an X drawing operation.
# 
# The function of the graphics context cache imp whose API
# we define here is to play "give me a pen and I'll give you
# a functionally equivalent graphics context".
#
# Since a given drawing op in general uses only a subset of
# the properties of a graphics context, the gc we return need
# match the pen in question only on the properties actually
# used.  Consequently, we accept "used" bitmaps specifying
# which properties actually matter for purposes of the current
# match operation.
#
# At this level we implement malloc/free style explicit
# gc management, using refcounts to track how many users
# a given gc currently has;  it is up to our caller to
# explicitly free a gc when done with it.

# Compiled by:
#     src/lib/x-kit/xclient/xclient-internals.sublib

# This api is implemented in:
#
#     src/lib/x-kit/xclient/src/window/pen-to-gcontext-imp-old.pkg

stipulate
    package dy = display_old;                                   # display_old   is from   src/lib/x-kit/xclient/src/wire/display-old.pkg
    package pg = pen_guts;                                      # pen_guts      is from   src/lib/x-kit/xclient/src/window/pen-guts.pkg
    package xt = xtypes;                                        # xtypes        is from   src/lib/x-kit/xclient/src/wire/xtypes.pkg
herein

    api Pen_To_Gcontext_Imp_Old {
        #
        Pen_To_Gcontext_Imp;

        make_pen_to_gcontext_imp
            :
            ( dy::Xdisplay,
              xt::Drawable_Id
            )
            ->
            Pen_To_Gcontext_Imp;


        allocate_graphics_context
            :
            Pen_To_Gcontext_Imp
            ->
            { pen:   pg::Pen,
              used:  Unt
            }
            ->
            xt::Graphics_Context_Id
            ;

        free_graphics_context
            :
            Pen_To_Gcontext_Imp
            ->
            xt::Graphics_Context_Id
            ->
            Void;

        allocate_graphics_context_with_font
            :
            Pen_To_Gcontext_Imp
            ->
            { pen:      pg::Pen,
              used:     Unt,
              font_id:  xt::Font_Id
            }
            ->
            ( xt::Graphics_Context_Id,
              xt::Font_Id
            );

        allocate_graphics_context_and_set_font
            :
            Pen_To_Gcontext_Imp
            ->
            { pen:      pg::Pen,
              used:     Unt,
              font_id:  xt::Font_Id
            }
            ->
            xt::Graphics_Context_Id;

        free_graphics_context_and_font
            :
            Pen_To_Gcontext_Imp
            ->
            xt::Graphics_Context_Id
            ->
            Void;

    };

end;

## COPYRIGHT (c) 1990, 1991 by John H. Reppy.  See SMLNJ-COPYRIGHT file for details.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.