image¶

draw a P8I picture, or grab the screen into one
NAME
    image - draw a P8I picture, or grab the screen into one

SYNOPSIS
    image /path/file            view a picture full-screen (any key returns)
    image x y file
    image read x0 y0 x1 y1 file

DESCRIPTION
    `image /path/file` (a bare ABSOLUTE path) is VIEW mode: it clears the
    screen, draws the picture full-screen at the top-left, and waits for a
    key before returning. This is how the Finder desktop opens a .P8I --
    select it and press ENTER (image quits back to Finder on any key).

    The two inverse verbs below run straight from the shell (no BASIC needed).

    `image x y file` draws a P8I picture with its top-left at (x,y) --
    SCREEN coordinates, y down: this shell command keeps the historical
    screen-space contract, unlike BASIC's IMAGE statement, which takes
    window coordinates (y up) anchored at the picture's bottom-left.
    (Both ride the same GL BLIT verb underneath -- one BLIT per row,
    the file bytes streamed verbatim as the payload.) The
    file carries its own width, height and depth, so nothing else is
    needed; a file that is missing prints ?No file, and one that is not
    P8I, the wrong version or depth, or ends early prints ?NOT P8I.
    Pixels past any screen edge are clipped by the engine, so a picture
    may hang off any side (x and y may be negative).

    `image read x0 y0 x1 y1 file` is the screen GRAB: it reads every
    pixel of the rectangle (any two opposite corners, sorted for you,
    coordinates 0-479 and 0-271) and writes it as a fresh P8I file,
    REPLACING any existing file of that name. Because P8I is
    self-describing, a grab is immediately re-drawable -- by this
    command, or by BASIC's IMAGE -- and can be lifted to a host machine
    (p8xfs get, then tools/p8img.py) as a real screenshot.

    A grab reads what the panel SHOWS: if the GL engine has been
    page-flipping (see man page), the command re-joins the pages first
    (a GL PGSYNC, stage 10b); each pixel is a GL PIXRD, answered
    through the read-back FIFO.
    The draw is BLIT-fast: the inner loop is one file byte to one port
    write, so a picture streams at wire speed on the card bridge. The
    C build at /binc/image.bin is behaviour-identical and slower; it
    exists for on-target comparison and rebuilding (man cc).
    The command establishes the GL ground state on entry (identity
    window and viewport) and leaves the pen WHITE.

EXAMPLES
    image 112 8 /examples/MANDRILL.P8I draw the demo photo
    image read 0 0 479 271 /SHOT.P8I   grab the whole screen
    image read 100 50 163 113 /Q.P8I   grab a 64x64 square
    image 200 100 /Q.P8I               ...and stamp it elsewhere

SEE ALSO
    basic (IMAGE statement), gfx, g3d, cube