## display.api
#
# newworld version of src/lib/x-kit/xclient/src/wire/display-old.api#
# Opening and closing a given screen
# on a given X server, and tracking
# information about currently open
# displays and screens.
#
# For the big picture here see
#
# src/lib/x-kit/xclient/src/window/xclient-ximps.pkg#
# which is the toplevel X session manager.
# In particular it has a dataflow diagram
# showing the major threads and their
# interactions.
#
#
#
# Nomenclature: "display" and "screen"
# =====================================
#
# X distinguishes between 'displays' and
# 'screens', with the idea that a given
# computer might have multiple "display"
# devices (e.g., graphics cards) each with
# multiple "screens" (monitors, say), with
# each display.screen combination being
# independently addressable by X clients.
# So you might have your mail client open
# up screen "0.0" and your web browser open
# up screen "0.1" and your stock tracker open
# up screen "1.0" and so forth.
#
# This is basically an idea that didn't work:
# in practice, even when modern personal
# computers have multiple graphics cards
# with multiple monitors each, they are
# all combined into a single display 0,
# screen 0 for purposes of X addressing.
#
# For example, my personal X box has
# three graphics cards each with two
# monitors for a total of six physical
# screens, but thanks to Xinerama they
# are all combined into a single screen
#
# "127.0.0.1:0.0"
#
# for xclient purposes -- e.g. fun open_xdisplay.
#
# BOTTOM LINE: 99.99% of the time the display.screen
# address you need is "0.0".
#
#
# Compiled by:
# src/lib/x-kit/xclient/xclient-internals.sublibstipulate
package xt = xtypes; # xtypes is from src/lib/x-kit/xclient/src/wire/xtypes.pkg package g2d = geometry2d; # geometry2d is from src/lib/std/2d/geometry2d.pkg package sj = socket_junk; # socket_junk is from src/lib/internet/socket-junk.pkgherein
# This api is implemented in:
#
# src/lib/x-kit/xclient/src/wire/display.pkg #
api Display {
#
exception XSERVER_CONNECT_ERROR String;
Xscreen = { id: Int, # Number of this screen -- almost always zero.
root_window_id: xt::Window_Id, # Root window id of this screen.
default_colormap: xt::Colormap_Id, # Default colormap.
white_rgb8: rgb8::Rgb8, # White and Black pixel values.
black_rgb8: rgb8::Rgb8,
root_input_mask: xt::Event_Mask, # Initial root input mask.
root_visual: xt::Visual,
backing_store: xt::Backing_Store,
visuals: List( xt::Visual ),
save_unders: Bool,
size_in_pixels: g2d::Size, # Width and height in pixels.
size_in_mm: g2d::Size, # Width and height in millimeters.
min_installed_cmaps: Int,
max_installed_cmaps: Int
};
Xdisplay = { socket: sj::Stream_Socket(Int), # Actual unix socket fd, wrapped up a bit. The 'Int' part is bogus -- I don't get what Reppy was trying to do with that phantom type.
#
name: String, # "host: display::screen" -- "foo.com:0.0" or such.
vendor: String, # Name of the server's vendor.
default_screen: Int, # Number of the default screen.
screens: List( Xscreen ), # Screens attached to this display.
pixmap_formats: List( xt::Pixmap_Format ),
max_request_length: Int,
image_byte_order: xt::Order,
bitmap_bit_order: xt::Order,
bitmap_scanline_unit: xt::Raw_Format,
bitmap_scanline_pad: xt::Raw_Format,
min_keycode: xt::Keycode,
max_keycode: xt::Keycode,
next_xid: Void -> xt::Xid # resource id allocator. Implemented below by spawn_xid_factory_thread() from src/lib/x-kit/xclient/src/wire/display-old.pkg };
# For background see comments to fun make_xsession in
#
# src/lib/x-kit/xclient/src/window/xsession-old.pkg #
# Here we:
# o Crack the display name to get the X server address.
# o Open a socket to the X server.
# o Do the initial handshake with the X server.
# o Decode the resulting info on available screes, visuals etc.
# o Set up a thread to read and report on errors from the X server.
#
open_xdisplay: { display_name: String, # ":0.0" or "192.168.0.1:0.0" or such, often from unix DISPLAY environment variable.
xauthentication: Null_Or( xt::Xauthentication )
}
->
Xdisplay;
close_xdisplay: Xdisplay -> Void;
depth_of_visual: xt::Visual -> Int;
display_class_of_visual: xt::Visual -> Null_Or( xt::Display_Class );
}; # api Xdisplay
end; # stipulate