[CREATE] RFC: Viewport Specification DRAFT

[Andrew Chadwick]

Here's the initial draft. I'll upload it to the wiki and make a
tracking bug about it once people's comments are in and applied.
Here's where I think it's weak:

* Needs use cases integrated.

* Could the language be clearer, and is my description of the
transformation correct?

* Elements of MyPaint's Cairo-based implementation taint things like
the coordinate system origin and the sense of rotation. Could this be
made more neutral?

* Do we need to store which of the views is the current one?

* Should dx and dy be integers?

----------------------8<-------------------------

Viewport spec
-------------

Status: draft

A viewport is a view into the document workspace. Each viewport consists
fundamentally of an affine transformation describing how document space maps to
device space, and incidentally a sized rectangle and some additional
information describing how implementations might choose to lay out the
viewports relative to one another and how big to make the user interface
element displaying each view. UI implementations may vary a lot.

Inside the root <image/> element of stack.xml, a single <views/> element may be
appended::

  <views>
    <!-- zero or more view elements -->
  </views>

It may contain any number of view elements, each of which describes a viewport
with its attributes::

  <views>
    <view dx="420" dy="-67" scale="1.0" rotation="37.5" mirrored="mirrored"
          path="0:1" w="1.0" h="0.5" />
    <view dx="-42" dy="567" scale="2.0" rotation="37.5"
          path="1" w="0.333" h="1.0" />
    <!-- ... -->
  </views>

Ordering does not matter for viewport reconstruction, but implementations are
free to discard any viewport that they do not wish to show, so it is wise for
implementations to save the largest or most important viewport first.

Viewport attribute definitions
------------------------------

The following attributes of a <view/> are defined:

dx, dy
  These describe the translation component of the affine transformation mapping
  document space to display space. They are applied first, and are floating-
  point pixel measurements in document space (and device space) whose positive
  sense is rightwards for x, and downwards for y.

rotation
  Optional. The rotation component of the transform, as a floating-point number
  of degrees in the range 0 <= n < 360. The rotation is applied second, around
  the top left pixel of the display space. Rotation values increase in the
  clockwise direction, and zero means no rotation at all. Support for rotations
  is strictly optional.

scale
  Optional. The scaling component of the transform, expressed as a nonzero
  positive floating point number. Implementations are free to ignore this, and
  may impose their own limits. Scaling is applied third, centred around the top
  left pixel of the display space. Implementations are not required to support
  scaling.

mirrored
  Optional. Whether the viewport is mirrored in a horizontal direction (value
  "mirrored"). Vertical mirroring should be implemented by adding 180° of
  rotation, and flipping the state of the mirroring attribute. Omitting the
  attribute means that horizontal mirroring should not be applied.

w, h
  Optional. The width and the height of the viewport's display, expressed as a
  floating point proportion of the available display space along the relevent
  axis. Values should be in the range 0<n<=1. Implementations should impose
  their own limits on these, and are free to ignore them entirely. Windowing
  implementations may use these as the size of the window; tiling
  implementations may set one to 1.0 and omit the other to indicate an
  orientation.

x, y
  Optional. The x and y position of the top left of the viewport's display,
  expressed as a floating point proportion of the available display space along
  that axis. Values should be in the range 0<n<1. Implementations should impose
  their own limits on these, and are free to ignore them entirely. Windowing
  implementations may use these as the position of the window; tiling
  implementations are likely to ignore them completely.

path
  Optional, and relevant only to tiling implementations. This is a colon-
  separated sequence of integers describing where each viewport goes in the
  tiling tree, with the node "0" being the first child of the top level, "1"
  being the 2nd child of the top level, and "1:0:2" being the 3rd child of the
  1st child of the 2nd child of the top level (!). Windowing implementations
  should ignore this. Tiling implementations may discard viewports which don't
  match their model of how the plane is divided up or which conflict with
  allocated space; they may also try to pack unpathed or incorrectly pathed
  viewports into a new structure, space permitting.

---------------------->8--------------------------

-- 
Andrew Chadwick