15.3.772  src/lib/x-kit/xclient/src/window/pen-cache.api

## pen-cache.api
#
# Track graphics-contexts in the X server.
#
# For the big picture see the imp dataflow diagrams in
#
#     src/lib/x-kit/xclient/src/window/xclient-ximps.pkg

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


stipulate
    include package   threadkit;                                                                # threadkit                                     is from   src/lib/src/lib/thread-kit/src/core-thread-kit/threadkit.pkg
    #
#   package x2s =  xclient_to_sequencer;                                                        # xclient_to_sequencer                          is from   src/lib/x-kit/xclient/src/wire/xclient-to-sequencer.pkg
    package pg  =  pen_guts;                                                                    # pen_guts                                      is from   src/lib/x-kit/xclient/src/window/pen-guts.pkg
    package v1u =  vector_of_one_byte_unts;                                                     # vector_of_one_byte_unts                       is from   src/lib/std/src/vector-of-one-byte-unts.pkg
    package xt  =  xtypes;                                                                      # xtypes                                        is from   src/lib/x-kit/xclient/src/wire/xtypes.pkg
herein


    # This api is implemented in:
    #
    #     src/lib/x-kit/xclient/src/window/pen-cache.pkg
    #
    api Pen_Cache
    {
        Pen_Cache;                                                                              # All non-ephemeral state for pen_cache.

        make_pen_cache
            :
            { drawable:         xt::Drawable_Id,
              next_xid:         Void -> xt::Xid,                                                # resource id allocator. Implemented by spawn_xid_factory_thread()    from   src/lib/x-kit/xclient/src/wire/display-old.pkg
              note_xrequest:    v1u::Vector -> Void                                             # See Note[1].
            }
            ->
            Pen_Cache;

        allocate_graphics_context
            :
            Pen_Cache
            ->
            { pen:              pg::Pen,
              used_mask:        Unt,
              note_xrequest:    v1u::Vector -> Void
            }
            ->
            xt::Graphics_Context_Id;                                                            # gc_id


        allocate_graphics_context_with_font
            :
            Pen_Cache
            ->
            { pen:              pg::Pen,
              used_mask:        Unt,
              note_xrequest:    v1u::Vector -> Void,
              font_id:          xt::Font_Id
            }
            ->
            { gc_id:            xt::Graphics_Context_Id,
              font_id:          xt::Font_Id
            };

        allocate_graphics_context_and_set_font
            :
            Pen_Cache
            ->
            { pen:              pg::Pen,
              used_mask:        Unt,
              note_xrequest:    v1u::Vector -> Void,
              font_id:          xt::Font_Id
            }
            ->
            xt::Graphics_Context_Id;                                                            # gc_id         

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

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


    };                                                                                          # api Pen_Cache
end;

##########################################################################
# Note[1]
# The point of using note_xrequest functions rather than passing in xsequencer
# itself, is that using note_xrequest lets our caller accumulate multiple requests
# and submit them as a block, allowing more efficient bulk processing downstream.
# (We also reduce risk of race conditions by using a single path to xerver_port.)