Window and photo command implementation

rbcWinop.c implements the standalone rbc::winop command when NO_WINOP is not defined. It owns no per-handle object: WinopCmd() selects an operation and passes the current Tk main window as client data. See the Tcl manual for command syntax; this chapter describes dispatch, resources and limitations.

Dispatch and platform boundaries

The direct winOps table and nested imageOps table are separate. ImageOp() validates its own operation/arity, then removes the image word by passing objc - 1 and objv + 1. Shared handlers consequently keep the same source/destination argument indices. Do not add a handler to one table assuming the other is an automatic alias: quantize is direct-only, while gradient and rotate are nested.

GetRealizedWindow() resolves a Tk path and creates its native window if necessary; it does not map it. StringToWindow() accepts paths or legacy Tcl integer IDs. Toplevel paths select wrappers. Numeric parsing uses Tcl_GetInt, so this path must not be described as accepting arbitrary pointer-width native handles. Windows numeric IDs pass through rbcWindowsResources.Rbc_WinWindowFromHWND(). See Shared drawing and window services for raw-handle versus drawable distinctions.

Window operations issue native map, unmap, stack and movement requests. Pointer query/warp uses screen or window coordinates, not graph data coordinates. The colormap operation is compiled only for X11. These operations neither participate in graph mapping nor acquire renderer contexts.

Native command contracts

Lower and raise accept Tk paths only. They resolve and restack each window in order, stop on a lookup error, and do not propagate Tk_RestackWindow status. Map and unmap also accept legacy integer IDs, but do not use StringToWindow(): numeric values are cast directly to Window. Their Tk-path branch realizes the client window, edits TK_MAPPED through Tk_FakeWin, and sends the native request. It does not select the toplevel wrapper or call Tk_MapWindow / Tk_UnmapWindow. Consequently, the conversion and wrapper rules of snap must not be generalized to these operations. Multi-window commands do not roll back earlier requests when a later argument is invalid; an empty window list succeeds.

Move validates both screen distances before Tk_MoveWindow and uses coordinates relative to the parent. Changes realizes a window, applies backing-store and save-under hints to a toplevel’s real window, and is a no-op for child windows. Successful submission does not guarantee that a server honors these hints.

Query reports root coordinates as @x,y. If XQueryPointer returns false, it returns TCL_OK without setting a new result. Warpto without an argument is a query; an @x,y argument selects the screen root, while a Tk path selects the center of a mapped window. These are native pointer operations and can generate events, but the handlers do not run a Tcl event loop themselves.

For numeric snapshot targets, GetWindowSize() has platform-specific geometry: Windows reads the outer GetWindowRect, while X11 uses XGetGeometry dimensions. The X11 implementation synchronizes before removing its scoped error handler, whose client data points to a stack-local flag. Failed queries leave output dimensions untouched; only dimension overflow adds a diagnostic in this helper. The Windows helper likewise writes dimensions only after a successful query.

Colormap is a legacy X11 diagnostic, not a general visual inspection API. It probes at most 256 writable cells, releases them, then queries IDs 0 through 255. Its bookkeeping assumes returned pixel IDs fit that range. Returned pairs identify cells not acquired by the probe; they do not identify their owners.

Photo-operation ownership

Most operations require existing Tk photos. Tk_FindPhoto handles and filter descriptors are borrowed. Color-image snapshots, transformed results and convolution kernels are owned locally and released through their matching APIs. Destination writes can notify Tk image clients; a handle lookup is not a lifetime guard. See Temporary images and private Tk adapters and Image storage and tile clients.

Operation

Work and sizing

Important boundary

convolve

Copy source; allocate kernel and output pixels

Nonempty square finite kernel and finite sum required

quantize

Resize destination, then copy source and destination

One to 256 colors; resizing precedes color-count validation

resample

Destination dimensions choose output size

Default none filter; equal sizes take a copy path

subsample

Validate source rectangle; resize into destination

Default box filter; positive extent and nonnegative origin

rotate

Evaluate angle, copy source, allocate rotated pixels

Finite degrees; Tcl expression evaluation can invoke callbacks

gradient

Allocate pixels at existing photo size and temporary Tk colors

Linear/radial/rectangular paths include random perturbation

readjpeg

Delegate file decoding into a borrowed destination

Returns an unsupported diagnostic without JPEG build support

snap

Capture native pixels, optionally resize

Captures a drawable; does not rerender a graph at export size

Gradient retains its historical formulas. Linear uses clamped random noise multiplied by the horizontal pixel index, rather than a normalized left-to-right ramp. Radial uses distance from the normalized center; rectangular uses a fixed rotation and Manhattan distance. Blank produces opaque white while still requiring valid endpoint colors. Tests must not assume deterministic pixels for the three randomized modes. Readjpeg delegates to the platform decoder only when JPEG support was compiled in; otherwise it fails before photo lookup.

Resample rejects source dimensions of one pixel or less. If either destination dimension is one pixel or less, it sets source dimensions and copies. Subsample instead uses the requested region dimensions for such a destination. Both resolve an optional vertical filter only when the first filter is non-NULL. The pixel algorithms and edge policies are described in Image resizing and resampling, Color-image rotation and bitmap transforms and Image color processing.

Failure and callback boundaries

These handlers do not provide a uniform transaction. Quantize can resize its destination before detecting an invalid color count. Several paths ignore Tk_PhotoSetSize / Tk_PhotoPutBlock status or publish via a void helper, so TCL_OK must not be interpreted as a checked commit of every lower-level photo write. Do not document a destination-unchanged-on-error guarantee for this family.

Rotate validates photo names before evaluating the angle, preserving the interpreter across Tcl_ExprDoubleObj. After evaluation it rejects destroyed Tk state and looks up both photos again before accessing pixels. Deleted photos produce an error; same-name replacements become the current source/destination. Expression errors retain their original diagnostic. This protects the angle callback boundary without changing the family’s photo-publication semantics.

Snap has a deliberate path-specific distinction: a Tk path uses the client window and Tk dimensions, while numeric IDs use native geometry lookup. Visibility and platform capture behavior matter. Tests should not confuse this with widget snap or SVG/PDF/PostScript output, which have their own rendering and restoration contracts.

Maintenance checks

Use the existing winop.*.test and winop.image.*.test families. Check direct and nested dispatch separately, invalid kernels and regions, source/destination dimensions, and toplevel snapshots on both platforms. These tests need a Tk display. Pixel algorithms alone cannot validate native capture, wrapper handling or photo client notifications.

Command registration

Rbc_WinopInit() registers the static dispatcher on an interpreter with Tk and the RBC namespace initialized. It creates no window and installs no client-data ownership or deletion callback.