XGTERM(1)

📦 version 2.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 xgterm(1) 💖

straight outta the General Commands Manual, section 1, and it's giving terminal emulator with graphics AND imaging energy ✨💅

🌸 NAME 🌸

xgterm — a terminal emulator for X with graphics and imaging capability 🎀

✨ SYNOPSIS ✨

xgterm [-toolkitoption ...] [-option ...]

🫶 DESCRIPTION 🫶

okay so bestie, listen up. xgterm is a terminal emulator for the X Window System, and it's based largely on xterm, but with a completely new graphics and imaging widget. It provides DEC VT102 and Tektronix 4014 compatible terminals for programs that can't use the window system directly. 👑

xgterm also serves as a prototype for the Widget Server being developed by the IRAF Project at NOAO. The Object Manager Library it uses implements a window system toolkit as an interpreted window-object language — which means application GUIs can be defined and executed at runtime without compiling any code, and with minimal dependence upon the underlying window system toolkit library. That's iconic fr. We will concentrate here, however, on its use as a terminal emulator and on a description of the new Gterm widget. 🦋

The Gterm graphics window operates almost identically to the xterm Tek window, however there are extensions for implementing full-screen cursors, imaging, area fills, colors, graphics erasure, a "status line" and so on. Any graphics application capable of running under an xterm Tek window should also be able to use xgterm as well. Client programs wishing to make use of the extended features, or those wishing to implement a GUI, are advised to use the OBM (Object Manager) library supplied with the XGterm source as part of the X11IRAF package. That gives you a much better programmatic interface to all of the features available; however, as of this writing it is not yet fully documented, ngl. Users are referred to the XImtool task as an example of a more complex application using the OBM Library and Gterm widget, as well as demo tasks in the guidemo directory of the X11IRAF sources. 🧚

The VT102 text window is unchanged from the original xterm application. All of its resources, command-line options and operation are identical to that used by xterm. The termcap(5) entry for xterm may be used for xgterm as well. See the xterm(1) man page for details. 💜

💅 OPTIONS 💅

All xterm(1) and X Toolkit command line options are supported, there are no additional options. periodt. that's the whole options section, bestie, it ate and left no crumbs 🍓

🌈 RESOURCES 🌈

The program understands all of the core X Toolkit resource names and classes, all text window resources known to xterm(1), as well as the Gterm (graphics and imaging widget) resources. The proper Class name for all resources described here is Gterm. A table of available Gterm resources and their defaults may be found below, and some of the more interesting resources are described here in detail: 😭

  • basePixel — Base cell of the custom colormap. This essentially allows you to reserve basePixel colors in the global colormap for other applications. The default is 38, and if you change it you'll also need to enable the cmapInitialize resource to force the Gterm widget to update its global colormap resource in the X server. 🔥
  • cmapInitialize — Initialize the ximtool colormap at startup. When resetting the basePixel resource or colormap, this is required in order to force the Gterm widget to update its global colormap resource in the X server. The default is False.
  • cmapInterpolate — Interpolate the colormap to the number of display colors. The default is True.
  • cmapName — Name used for private colormap. The default for all IRAF imaging applications is image. Gterm widget based imaging applications which have the same value of cmapName will share the same colormap, minimizing colormap flashing and allowing multiple applications to be run at the same time. ✨
  • color0 — The widget background color. The default is black.
  • color1 — The widget foreground color. The default is white.
  • color2 thru color9 — Optional drawing colors. The line color used for graphics is set using an escape sequence to select the current color index. See Gterm I/O Escape Sequences below for more details.
  • crosshairCursorColor — Color of the full screen crosshair cursor. 🎯
  • defaultMarker — Default marker type. Options include text, line, polyline, rectangle, box, circle, ellipse, and polygon. The default is rectangle.
  • deiconifyWindow — De-iconify the Gterm graphics window when activated. The default is False.
  • dialogBgColor — Dialog box (i.e. the status line) background color. Dialog text is text which is drawn into the dialog area at the bottom of the gterm window, it is transient and is not a permanent part of the graphics being drawn. Dialog text is normally used to interact with the user or to display messages during program operation, without affecting the graphics being drawn.
  • dialogFgColor — Dialog box (i.e. the status line) foreground color.
  • ginmodeBlinkInterval — Graphics cursor blink interval, time is specified in milliseconds. The default is 0.
  • ginmodeCursor — Graphics mode cursor type. The default is a full screen cursor custom to the widget.
  • height — Height of the Gterm window. The default is 480.
  • idleCursor — Cursor to use when not in graphics mode. The default is a plus sign.
  • markerHighlightColor — Highlight color for the active marker. When the pointer moves into a marker it is marked "active", and the highlight color and width change to which marker is active. The default is green. 💚
  • markerHighlightWidth — Highlight width for the active marker. The default is 2.
  • maxColors — The maximum number of colors to use in the private global colormap, the default is 216. Out of this number 10 colors (the color0 thru color9 values) are reserved by the widget as static colors, the remainder may be allocated for images.
  • raiseWindow — Raise the window when active. The default is False.
  • warpCursor — Warp the cursor to the window when active. The default is False.
  • width — Width of the Gterm window. The default is 640.

👑 GTERM WIDGET RESOURCES 👑

🦋 Class Hierarchy 🦋

Core -> Gterm

⭐ Resources ⭐

When creating a Gterm widget instance, the following resources are retrieved from the arguments list or from the resource database:

Name                     Class Type    Default          Description
  • alphaFont1 — XFontStruct, default nil2 — one of the graphics fonts 🎀
  • alphaFont2 — XFontStruct, default 5x8 — graphics fonts too 💅
  • alphaFont3 — XFontStruct, default 6x10 — graphics fonts, yes again ✨
  • alphaFont4 — XFontStruct, default 7x13 — graphics fonts, still going 🌸
  • alphaFont5 — XFontStruct, default 8x13 — graphics fonts 🦋
  • alphaFont6 — XFontStruct, default 9x15 — graphics fonts, no cap 💖
  • alphaFont7 — XFontStruct, default 9x15 — graphics fonts 🫶
  • alphaFont8 — XFontStruct, default 9x15 — graphics fonts, the whole set 😭
  • basePixel — Int, default 38 — the base of the private global colormap 🌈
  • busyCursor — String, default watch — which cursor shows up when the app is busy 👀
  • busyCursorBgColor — Foreground, default white — busy cursor background color
  • busyCursorFgColor — Foreground, default black — busy cursor foreground color
  • cacheRasters — String, default whenNeeded — saves rasters as server pixmaps so access is faster ⚡
  • cmapInitialize — Boolean, default False — initializes the colormap at startup
  • cmapInterpolate — Boolean, default True — interpolate the colormap
  • cmapName — String, default default — custom colormap name
  • cmapShadow — Int, default 10 — colormap shadow interval
  • cmapUpdate — Int, default 60 — colormap update interval
  • color0 — Background, default black — default graphics background color 🖤
  • color1 — Foreground, default white — default graphics foreground color 🤍
  • color2 — Foreground, default red — optional drawing color ❤️
  • color3 — Foreground, default green — optional drawing color 💚
  • color4 — Foreground, default blue — optional drawing color 💙
  • color5 — Foreground, default cyan — optional drawing color 🩵
  • color6 — Foreground, default yellow — optional drawing color 💛
  • color7 — Foreground, default magenta — optional drawing color 💜
  • color8 — Foreground, default purple — optional drawing color 💟
  • color9 — Foreground, default darkslategray — optional drawing color 🩶
  • copyOnResize — Boolean, default True — copy the raster when it gets resized
  • crosshairCursorColor — Foreground, default red — full-screen cursor color
  • defaultMarker — String, default rectangle — the default marker type
  • deiconifyWindow — Boolean, default False — deiconify the window when it's active
  • dialogBgColor — Foreground, default yellow — status line background color
  • dialogFgColor — Foreground, default black — status line foreground color
  • dialogFont1 — XFontStruct, default nil2 — status line fonts 🎀
  • dialogFont2 — XFontStruct, default 5x8 — status line fonts
  • dialogFont3 — XFontStruct, default 6x10 — status line fonts
  • dialogFont4 — XFontStruct, default 7x13 — status line fonts
  • dialogFont5 — XFontStruct, default 8x13 — status line fonts
  • dialogFont6 — XFontStruct, default 9x15 — status line fonts
  • dialogFont7 — XFontStruct, default 9x15 — status line fonts
  • dialogFont8 — XFontStruct, default 9x15 — status line fonts, the whole lil family ✨
  • ginmodeBlinkInterval — Int, default 0 — graphics cursor blink interval
  • ginmodeCursor — String, default full_crosshair — graphics cursor type
  • ginmodeCursorBgColor — Foreground, default black — graphics cursor background color
  • ginmodeCursorFgColor — Foreground, default white — graphics cursor foreground color
  • height — Dimension, default 480 — height of graphics window
  • idleCursor — String, default Plus — idle cursor type
  • idleCursorBgColor — Foreground, default white — idle cursor background color
  • idleCursorFgColor — Foreground, default black — idle cursor foreground color
  • markerBoxKnotColor — Foreground, default blue — vertex knot color
  • markerBoxKnotSize — Int, default 0 — vertex knot size
  • markerBoxLineColor — Foreground, default green — marker border color
  • markerCircleKnotColor — Foreground, default blue — vertex knot color
  • markerCircleKnotSize — Int, default 0 — vertex knot size
  • markerCircleLineColor — Foreground, default green — marker border color
  • markerCursorBgColor — Foreground, default black — cursor background when you're in a marker
  • markerCursorFgColor — Foreground, default yellow — cursor foreground when you're in a marker
  • markerEllipseKnotColor — Foreground, default blue — vertex knot color
  • markerEllipseKnotSize — Int, default 0 — vertex knot size
  • markerEllipseLineColor — Foreground, default green — marker border color
  • markerFill — Boolean, default False — flood fills the marker area with markerFillColor 🎨
  • markerFillBgColor — Foreground, default black — fill area background color
  • markerFillColor — Foreground, default slategray — flood fill color
  • markerFillStyle — Int, default FillSolid — fill area style
  • markerHighlightColor — Foreground, default green — marker highlight color
  • markerHighlightWidth — Int, default 2 — marker highlight line width
  • markerLineKnotColor — Foreground, default blue — vertex knot color
  • markerLineKnotSize — Int, default 5 — vertex knot size
  • markerLineLineColor — Foreground, default green — line marker color
  • markerLineStyle — Int, default LineSolid — line marker line style
  • markerLineWidth — Int, default 1 — line marker width
  • markerPgonKnotColor — Foreground, default blue — vertex knot color
  • markerPgonKnotSize — Int, default 5 — vertex knot size
  • markerPgonLineColor — Foreground, default green — marker border color
  • markerRectKnotColor — Foreground, default blue — vertex knot color
  • markerRectKnotSize — Int, default 0 — vertex knot size
  • markerRectLineColor — Foreground, default green — marker border color
  • markerTextBgColor — Foreground, default slategray — text marker background color
  • markerTextBorder — Int, default 2 — text marker border width
  • markerTextColor — Foreground, default yellow — text marker text color
  • markerTextFont — XFontStruct, default 6x13 — text marker font
  • markerTextLineColor — Foreground, default green — text marker line color
  • markerTextString — String, default NULL — the text string
  • markerTranslations — String, default default — marker event-to-actions translations
  • maxColors — Int, default 216 — max colors in a custom colormap
  • maxMappings — Int, default 32 — max image mappings
  • maxRasters — Int, default 512 — max image rasters
  • nearEdge — Int, default 1 — the distance, in pixels, between the pointer and the marker edge that's required for translation actions to be in effect 📏
  • nearVertex — Int, default 4 — the distance, in pixels, between the pointer and the marker vertex (that's the knot, bestie) that's required for translation actions to be in effect 📐
  • raiseWindow — Boolean, default False — raise the window when it's active
  • translations — String, default default — event-to-actions translations
  • useTimers — Boolean, default True — ok to use timers ⏰
  • warpCursor — Boolean, default False — enable warp cursor when active
  • width — Dimension, default 640 — and the description says "Height of graphics window", which is genuinely what it says, i'm just the messenger 💀

🌈 GTERM WIDGET TRANSLATIONS AND ACTIONS 🌈

ok so the default translations for a Gterm window are literally this:

      <Btn1Down>:   m_create()
      <Btn2Down>:   crosshair(on)
    <Btn2Motion>:   crosshair(on)
        <Btn2Up>:   crosshair(off)
   <EnterWindow>:   enter-window()
   <LeaveWindow>:   leave-window()
      <KeyPress>:   graphics-input()
        <Motion>:   track-cursor()

and these are the action procedures you can use on a Gterm window, periodt:

  • ignore() — ignore an event. that's it. that's the whole job 🙈
  • graphics-input() — handle a graphics input request 🎮
  • crosshair(on|off) — display a crosshair cursor ✨
  • track-cursor() — track the crosshair cursor position 👀
  • enter-window() — handle an EnterWindow event 🚪
  • leave-window() — handle a LeaveWindow event 👋
  • reset() — do a soft reset of the Gterm widget 🔄
  • m_create() — create a new marker, icon behavior 💅. the valid types include:
    • text
    • line
    • polyline
    • rectangle
    • box
    • circle
    • ellipse
    • polygon

and if you don't give a type at all, the default is rectangle — or, more precisely, the default type specified by the markerType resource gets used 🎀

✨ GTERM MARKER TRANSLATIONS AND ACTIONS ✨

okay bestie, here's the tea on markers ☕️💅 the default translations for a marker are literally this:

                  !Shift <Btn1Motion>:   m_rotateResize()
                         <Btn1Motion>:   m_moveResize()
                    !Shift <Btn1Down>:   m_raise()  m_markpos()
                           <Btn1Down>:   m_raise()  m_markposAdd()
                             <Btn1Up>:   m_redraw() m_destroyNull()
                           <Btn2Down>:   m_lower()
                       <Key>BackSpace:   m_deleteDestroy()
                          <Key>Delete:   m_deleteDestroy()
                           <KeyPress>:   m_input()
                             <Motion>:   track-cursor()

Translations affect only the currently active marker, the cursor must be within nearEdge pixels of a marker edge, or nearVertex pixels of a marker vertex to take effect. so picky, but we respect it 💅

The available action procedures for a marker are lowkey iconic:

  • m_create(type) — Create a new marker. Valid types include text, line, polyline, rectangle, box, circle, ellipse, polygon. The default is rectangle, if no type is given the default type specified by the markerType resource will be used.
  • m_destroy() — Destroy the active marker.
  • m_destroyNull() — Destroy the active marker if it is null sized.
  • m_set(attribute, value, ....) — Set a marker attribute. Valid attributes include:
activated   autoRedraw       fill          fillBgColor
fillColor   fillPattern      fillStyle     font
height      highlightColor   imageText     knotColor
knotSize    lineColor        lineStyle     lineWidth
rotangle    sensitive        textBgColor   textBorder
textColor   translations     type          visible
width       x                y
  • m_raise() — Raise the active marker to the top of the display list.
  • m_lower() — Lower the active marker to the bottom of the display list.
  • m_notify(event, event, ....) — Notify any clients that have registered callbacks for the specified type of events. Recognized events include:
notify    moveResize   modify
redraw    destroy      input
focusIn   focusOut     constraint
  • m_input() — Notify any clients that have registered a input callback that a input event has occurred.
  • m_markpos() — Mark the current position of the marker, e.g., so that it can later be erased.
  • m_markposAdd() — Execute either the markpos or add action, depending upon the pointer location. If the pointer is over an active marker at a location where the add action can be executed this is done, otherwise the markpos action is executed.
  • m_redraw() — Redraw the active marker.
  • m_addPt() — Add a point (i.e. vertex knot). Polyline and polygon markers only.
  • m_deletePt() — Delete a point (i.e. vertex knot).
  • m_movePt() — Move a point (i.e. vertex knot). Polyline and polygon markers only.
  • m_deleteDestroy() — Delete a point or destroy a marker, depending upon the pointer position.
  • m_move() — Move a marker.
  • m_resize() — Resize a marker.
  • m_moveResize() — Move a point or marker, or resize a marker, depending upon the pointer position.
  • m_rotate() — Rotate a marker.
  • m_rotateResize() — Rotate or resize a marker. A marker is rotated if near a vertex know, or resized if near an edge.

🦋 GTERM I/O ESCAPE SEQUENCES 🦋

XGterm uses escape sequences to provide graphics emulation. This protocol is an extension of the Tektronix 4012 graphics protocol. The basic extensions are patterned after the Retrographics VT640 graphics terminal, using GS (octal \035, aka Ctrl-]) and CAN (octal \030, aka Ctrl-x) to switch between vt100 and graphics modes. Additional extensions are defined to support advanced features such as color, area fills, graphics erasure, setting the cursor location under program control, interactive dialog via the "status line", and so on. the range? iconic. 🌈

While these escape sequences can be used directly, the best programmatic interface is to use the OBM (Object Manager) library supplied with the XGterm source as part of the X11IRAF package. Any Tektronix-compatible graphics library will suffice for producing vector graphics, the added escape sequences used by the Gterm widget are required to make use of imaging, area fills, the status line, etc.

All escape sequences begin with an ESC character (octal \033), followed by up to three characters defining the action to be taken. All strings in capital letters refer to the ASCII code (e.g. LF is the ASCII linefeed code), a three digit number preceded by a '´ refers to an octal code (e.g. " 12" is octal 12) , all others are characters in the escape code (e.g. "/bc" are the three characters /, b, and c).

🌈 ESCAPE SEQUENCES 🌈

  • US — (no description given, just a mysterious queen 💅✨)
  • CR — Switch to alpha mode. Characters are drawn in the graphics window at the "current" position (normally set beforehand with a GS/US vector move), using the alpha mode font. Receipt of any control code causes alpha mode to be exited.
  • GS — Switch to vector polyline mode.
  • FS — Switch to vector polypoint mode.
  • RS — Switch to vector mode, vertices are joined as a polygon.

With all three codes, vertices and points are accumulated in a buffer and displayed when the buffer fills or when vector mode is terminated by receipt of any control code. A workstation open will be done if it hasn't already been opened, no-op sequences GS-CAN are filtered out, since they would only cause a pointless switch to the graphics frame and back without drawing. The open workstation sequence is GS,US, or by the xterm graphics start escape sequence "[?38h".

  • EM — Enter message mode. In message mode input text is accumulated in a buffer and eventually passed to the object manager, which delivers the message to the referenced object. Messages are used to download the user interface to be executed by the object manager. During execution, messages are used to set the values of user interface parameters to allow the UI to track the state of the client application.
  • CAN — Close workstation and enter command mode.
  • BEL — Ring the screen bell.
  • ENQ — Return terminal status. Returned values include the terminal mode, and alpha cursor x and y position.
  • SUB — Initiate a cursor read, values are returned in window coordinates.
  • /SUB — Return window cursor position in raster coordinates.
  • FF — Clear the screen.
  • /f — Set current cursor position.
  • 0 — Set character size 0. (Currently ignored).
  • 1 — Set character size 1. (Currently ignored).
  • 2 — Set character size 2. (Currently ignored).
  • 3 — Set character size 3. (Currently ignored).
  • /0d — Set color index.
  • /1d — Clear graphics screen.
  • /2d — Invert graphics screen
  • ` — Select line style 0. (Solid)
  • a — Select line style 1. (Dashed)
  • b — Select line style 2. (Dotted)
  • c — Select line style 3. (DashDot)
  • d — Select line style 4. (Dash3Dot)
  • /0w — Select line width 0.
  • /1w — Select line width 1.
  • /2w — Select line width 2.
  • /nw — Select line width 3.
  • /0c — Select line color 0.
  • /1c — Select line color 1.
  • /2c — Select line color 2.
  • /3c — Select line color 3.
  • /4c — Select line color 4.
  • /5c — Select line color 5.
  • /6c — Select line color 6.
  • /7c — Select line color 7.
  • /8c — Select line color 8.
  • /9c — Select line color 9.

💖 IMAGING ESCAPE SEQUENCES 💖

These are encoded as follows:

ESC <code> [ P ; P ; ... ] <data>

where code is a character sequence and P is an ASCII encoded parameter described below.

  • /nc — Select line color. Parameter is the color number in the range 0-9.
  • sre — Reset. Parameters are "reset-str".
  • ssz — Resize. Parameters are "resize-str".
  • rir — Initialize raster.
  • rcr — Create a raster. Parameters are raster number, type, width, height, and depth. Type is 1 for a normal (client) raster, 2 for cached in server memory, or 0 if you don't care. Depth may be 1, 8, 16, or 32.
  • rde — Destroy a raster. Parameter is raster number.
  • rqr — Query a raster. Parameter is raster number. Output parameters are status, type, width, height, and depth encoded in the string ""\033[5;%d;%d;%d;%d;%d]".
  • rsr — Select a raster. Parameter is raster number.
  • rwr — Write pixels to a rectangular region of a raster. Parameters are raster number, encoding type (not used), x1, y1, nx, ny, and depth followed by (nx*ny) data pixels.
  • rrd — bestie, this one reads from a rectangular region of a raster 📖✨ Parameters are raster number, encoding type (not used, girl is just vibing there 💀), x1, y1, nx, ny, and depth, followed by (nx*ny) data pixels.
  • rrp — Refresh raster pixels 🎀 Parameters are raster number, coordinate type (0 for pixel, 1 for NDC), x1, y1, nx, ny.
  • rsp — Sets every single raster pixel in a region to one single color, no cap 💅 Parameters are raster number, coordinate type (0 for pixel, 1 for NDC), x1, y1, nx, ny, color, and raster operand. And listen — if nx=ny=0 the entire raster gets written, like the whole thing, she ate 🍽️ Raster operands include transient (octal 020), refresh_all (octal 040), or refresh_none (octal 100).
  • rco — Copy a region of the source raster to a region of the destination raster 🦋 Parameters are raster operand, source raster number, source type, source x coord, source y coord, source width, source height, destination raster number, destination type, destination x coord, destination y coord, destination width, destination height. If the input and output regions are not the same size, the subimage is automatically scaled to fit the destination region — the way she just adapts? iconic ✨ If the destination extent DNX or DNY is negative, the image is flipped in that axis 🙃 The type of spatial scaling performed is determined by the scale factors (zoom, dezoom, or no scaling). The rasterop argument is used to exercise fine control over how the mapping is performed, e.g. to force a refresh, implement a transient mapping, or in the case of a dezoom (many-to-one) mapping, select the antialiasing technique to be used.
  • rwc — Write a colormap 🎨 Parameters are colormap number, first color and the number of colors, followed by NC colors triples in the data.
  • rrc — Returns the color assignments for a region of the named colormap 🌈 Parameters are colormap number, first color and the number of colors, followed by NC colors triples in the data.
  • rlc — Load a colormap into the display, optionally scaling the colormap via a linear transformation in the process 💜 Parameters are the colormap number, the offset value, and the cursor x and Y coordinates in NDC units. Heads up: the colormap is unaffected if offset=0.5, scale=1.0. A negative scale inverts the image (flip era 🫶). If map=0 the linear transformation is applied directly to the display colormap.
  • rwo — Write the IOmap 👑 Parameters are the first color and the number of colors, followed by NC color triples in the data. An iomap is an optional lookup table used to isolate the client application from the color model used within the Gterm widget. To simplify color allocation the Gterm widget defines a logical color space where color 0 is the background, 1 the foreground, 2-N are statically allocated standard colors, and colors N+1 and above are dynamically allocated by the graphics application. Less-demanding applications use only the statically allocated, shared colors. The widget internally maps these logical colors to whatever the window system requires, but providing a well-defined logical color space isolates the client from the details of color allocation in the underlying window system.

An iomap can be used to define a mapping between the color model of the client application and the Gterm color model (when we say color model here we mean color allocation schemes for 8 bit pseudocolor). By default the iomap is one-to-one, fr fr. The use of an iomap frees the client from having to worry about color index translations, and allows color tables to be combined in the widget for greater efficiency when color tables are serially applied. The iomap applies to all color indices or pixel values passed in i/o operations between the client and the Gterm widget 💖

  • rro — Read the IOmap 📖 Return values are the first color and the number of colors, followed by NC color triples in the data.
  • rim — Delete all mappings and initialize the mapping subsystem 🧹 clean slate energy, periodt.
  • rsm — Define a new mapping function, or modify an old one 💫 If a new mapping is defined it is merely enabled, and no refreshing of the screen takes place until either some mapped data is written to or the mapping is explicitly refreshed. If an existing mapping is modified the old and new mappings are examined and only those portions of the destination rect for which the mapping changed are updated. This permits minor changes to a mapping (e.g. moving an edge) without having to redraw the entire region. Regions of the destination drawable which were previously covered by the mapping but which were exposed by modifying the mapping are redrawn — she's efficient, she's thoughtful, she's the moment 🌸
  • rgm — Return the external parameters of a mapping 🔍 Parameter is the mapping number, values returned (in the string "\033[6;%d;%d %d;%d;%d;%d;%d;%d %d;%d;%d;%d;%d;%d]") are the mapping number, rasterop, source mapping, type, x, y, width, height, and destination mapping, type, x, y, width and height.
  • rem — Enable a mapping ⭐ Parameters are the mapping number and an integer flag indicating whether to refresh the mapping.
  • rdm — Disable a mapping 🙈 Disabling a mapping does not affect the mapping definition, hence a disabled mapping may later be reenabled. Parameters are the mapping number and an integer flag indicating whether to erase the mapping.
  • rrm — Refresh a mapping 🔥 Parameter is the mapping number.
  • rfm — Free a mapping 🕊️ Parameter is the mapping number.

🌈 MORE ON IMAGING 🌈

okay bestie, so the Gterm widget's imaging model is built out of three key object/data types: rasters, mappings, and colors. let's go 💖

raster

A raster is a MxN array of pixels. right now, pixels are 8 bits deep, but there are hooks built into the widget to expand that in the future. Pixel values are indices into the Gterm virtual colormap, and those values start at zero. A raster can literally be any size you want. A raster is just a two-dimensional array sitting in the graphics server — it does not get displayed unless it's mapped. (One exception, and it's a big one: raster zero, which is the graphics window. 👑)

Rasters are referred to by number, starting with zero. At first, only raster zero exists; you make new ones with the create raster escape code rcr. Space for rasters may be allocated either in the graphics server or in the X server. This has implications for performance but is otherwise transparent to the client. By default, rasters are allocated in the graphics server, i.e., in the X client.

mapping

A mapping defines a projection of a rectangle of the source raster onto a rectangle of the destination raster. Mappings may be either enabled (active) or disabled. When a mapping is enabled, any change to a pixel in the source rect will cause the corresponding pixels in the destination rect to be updated. Mappings are referred to by number, starting with one. Initially, no mappings are defined. ✨

If the size of the input and output rect isn't the same, the input rect gets scaled by pixel replication or subsampling to fill the output rect. And here's the fun part: if the argument DW (destination width) or DH (destination height) of the destination rect is negative, the image will be flipped around the corresponding axis when copied to the destination — and the region of the destination drawn into is the same in either case. 🙈

Multiple mappings may reference the same source or destination raster. Mappings are refreshed in order by the mapping number. Modifying a mapping causes the changed regions of the destination rect to be refreshed.

color

The Gterm widget provides a fixed number of preassigned colors corresponding to pixel values 0 through 9. Zero is the background color, one is the foreground color, and 2-9 (that's 8 colors) are arbitrary colors defined by Gterm widget resources. These static colors are normally used to draw the background, frame, axes, titles, etc. of a plot, or to draw color graphics within the drawing area. The advantage of static colors is that they're shared with other X clients, and the values of these colors may be assigned by the user to personalize the way plots look. cute, right? 🎀

The Gterm widget also allows any number (up to about 200 or so) of additional colors to be defined at runtime by the client application. These color values start at pixel value 10 and go up to the maximum pixel value assigned by the client. The client application allocates colors with the write colormap escape code rwc. Attempts to overwrite the values of the static colors are ignored. The values of already allocated colors may be changed dynamically at runtime using write colormap code to write the desired range of color values.

Applications should not assume that there are 10 static colors and 200 or so allocatable colors. The IRAF graphcap entry for the logical device in use, and resources set for the widget, defines these parameters for the device. Alternatively, the read colormap code may be used to dynamically determine how many colors the server has preallocated when the application starts up.

An image may use either static and dynamic pixel values or both types of values, but in most cases imaging applications involve smoothly shaded surfaces, hence will require dynamically assigned private colors.

If for some reason the client application cannot use the Gterm widget color model, the IOMAP feature can be used to make the widget appear to have some externally defined (i.e., client defined) color model.

The maximum number of rasters and maximum number of mappings is defined by the Gterm widget resources maxRaster and maxMappings (or in the GUI file) when the graphics application starts up. The maximum values should be much larger than most applications require. Applications should allocate raster or mapping numbers sequentially starting at 1 (more or less) to avoid running out of raster or mapping descriptors. no cap, just be tidy 💅

The {read|write}pixels escape codes operate directly on raster pixels. The mapping escape codes support two alternative coordinate systems, raster pixels and NDC (normalized device coordinates), as indicated by the ST or DT argument (source or destination coordinate type). Note that the origin of the pixel coordinate system is the upper left corner of the display window (consistent with most graphics systems), whereas the origin of the NDC coordinate system is the lower left corner (consistent with IRAF). ✨

Pixel coordinates allow precise control of imaging but require the application to know the window size, and may result in complications e.g. if the window is resized. NDC coordinates pretty much guarantee that a mapping will involve sampling, hence are not the most efficient, but the graphics will be drawn correctly no matter how the window is resized, and for most applications the performance difference is negligible. Most applications should use NDC coordinates for raster 0 (the display window), and pixel coordinates for rasters 1-N.

Although the size of rasters 1 and higher are defined by the client application, the size of raster zero — the actual gterm display window — is subject to the constraints of the window system. The client can attempt to reset the size of the gterm window using create raster escape with raster=0, however the Gterm widget, UI containing the Gterm widget, and the window manager are all free to deny such a request. 🫠 The query raster escape should be called to determine the actual size of the window one will be drawing into.

AN EXAMPLE IMAGING APPLICATION

An example of a simple imaging application might be one that downloads an image and displays it in the gterm window, filling the window. This could be done as follows (following a graphics open and other escape codes to prepare the drawing surface):

  • create raster — Create raster 1, the size of the pixel array to be displayed. This need not be the same as the size of the gterm display window.
  • set mapping — Define a mapping between raster 1 and raster 0, the display window, using NDC coordinates to define the region of the display window to be filled. The mapping number is arbitrary but mappings should normally be allocated starting with 1. The mapping is automatically enabled when first defined.
  • write colormap — (Optional). Define the pixel value to RGB color assignments for the image pixels.
  • write pixels — This escape is called one or more times to write pixels into raster 1. At most 32K pixels can be written in each call. As each write is made, the affected region of the display window will be updated.

Alternatively, one could write the pixels and then define the mapping to cause the entire image to be displayed at once.

Note that the imaging escape can be combined with normal graphics to draw text and graphics around or on top of an image region. The order in which drawing operations occur is important — e.g., to draw graphics or text on top of an image, the image should be drawn first. 🎨

🦋 MARKERS 🦋

Markers are a general feature of the Gterm widget and are used more extensively in other programs (e.g. the prototype IRAF science GUI applications), but they have no real use in xgterm when used as simply a graphics terminal. All markers share some of the same characteristics, so it's worthwhile learning the basic marker manipulation keystrokes (as defined using the default marker translations) — especially how to delete an accidentally created marker 😭:

  • o Delete or Backspace in a marker deletes it.
  • o MB1 anywhere inside a marker may be used to drag the marker.
  • o MB1 near a marker corner or edge, depending on the type of marker, resizes the marker.
  • o Shift-MB1 on the corner of most markers will rotate the marker.
  • o Markers stack, if you have several markers and you put one on top of the other. The active marker is highlighted to tell you which of the stacked markers is active. If the markers overlap, this will be marker "on top" in the stacking order.
  • o MB2 in the body of a marker "lowers" the marker, i.e. moves it to the bottom of the stacking order.

🌸 ENVIRONMENT 🌸

XGterm sets the environment variables TERM'' and TERMCAP'' properly for the size window you have created. It also uses and sets the environment variable DISPLAY'' to specify which bit map display terminal to use. The environment variable WINDOWID'' is set to the X window id number of the xgterm window. 🌈

👑 SEE ALSO 👑

xterm(1), resize(1), X(1), pty(4), tty(4)

Xterm Control Sequences (in the xterm source directory)

💀 BUGS 💀

Many of the same bugs affecting xterm also apply here. fr fr.

Xgterm is not normally installed with setuid permissions. On some Linux systems, for example, where the /dev/tty and /dev/pty devices have root ownership and permission 600, this can cause problems. Workarounds are to either install XGterm with setuid permissions or modify the /dev/tty and /dev/pty devices to have permission 666.

bestie please read that one twice, it's giving permissions chaos and you do NOT want to be surprised by it 🙈

Copyright(c) 1986 Association of Universities for Research in Astronomy Inc.

and that's a wrap on the whole page, mwah 💖 this bad boy is the X11IRAF Project special, dated 16 Dec 1996, filed under XGTERM(1). slay, go image something iconic ✨👑

📦 where this page comes from