Maintainer | diagrams-discuss@googlegroups.com |
---|

The core library of primitives forming the basis of an embedded domain-specific language for describing and rendering diagrams.

Graphics.Rendering.Diagrams.Core defines types and classes for primitives, diagrams, and backends.

- type UpAnnots v m = Bounds v ::: (NameMap v ::: (Query v m ::: Nil))
- type DownAnnots v = Split (Transformation v) ::: (Style ::: (AM [] Name ::: Nil))
- newtype AnnDiagram b v m = AD {
- unAD :: UDTree (UpAnnots v m) (DownAnnots v) (Prim b v)

- mkAD :: Prim b v -> Bounds v -> NameMap v -> Query v m -> AnnDiagram b v m
- type Diagram b v = AnnDiagram b v Any
- prims :: (HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => AnnDiagram b v m -> [(Prim b v, (Split (Transformation v), Style))]
- bounds :: (OrderedField (Scalar v), InnerSpace v, HasLinearMap v) => AnnDiagram b v m -> Bounds v
- names :: HasLinearMap v => AnnDiagram b v m -> NameMap v
- query :: (HasLinearMap v, Monoid m) => AnnDiagram b v m -> Query v m
- sample :: (HasLinearMap v, Monoid m) => AnnDiagram b v m -> Point v -> m
- atop :: (HasLinearMap v, OrderedField (Scalar v), InnerSpace v, Monoid m) => AnnDiagram b v m -> AnnDiagram b v m -> AnnDiagram b v m
- named :: forall v b n m. (IsName n, HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => n -> AnnDiagram b v m -> AnnDiagram b v m
- withName :: HasLinearMap v => Name -> (Point v -> AnnDiagram b v m -> AnnDiagram b v m) -> AnnDiagram b v m -> AnnDiagram b v m
- freeze :: forall v b m. (HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => AnnDiagram b v m -> AnnDiagram b v m
- data Prim b v where
- Prim :: Renderable t b => t -> Prim b (V t)

- nullPrim :: (HasLinearMap v, Monoid (Render b v)) => Prim b v
- class (HasLinearMap v, Monoid (Render b v)) => Backend b v where
- data Render b v :: *
- type Result b v :: *
- data Options b v :: *
- withStyle :: b -> Style -> Transformation v -> Render b v -> Render b v
- doRender :: b -> Options b v -> Render b v -> Result b v
- adjustDia :: Monoid m => b -> Options b v -> AnnDiagram b v m -> AnnDiagram b v m
- renderDia :: (InnerSpace v, OrderedField (Scalar v), Monoid m) => b -> Options b v -> AnnDiagram b v m -> Result b v

- class Backend b v => MultiBackend b v where
- renderDias :: b -> Options b v -> [AnnDiagram b v m] -> Result b v

- class Transformable t => Renderable t b where

# Diagrams

## Annotations

type UpAnnots v m = Bounds v ::: (NameMap v ::: (Query v m ::: Nil))Source

Monoidal annotations which travel up the diagram tree, i.e. which are aggregated from component diagrams to the whole:

- functional bounding regions (see Graphics.Rendering.Diagrams.Bounds)
- name/point associations (see Graphics.Rendering.Diagrams.Names)
- query functions (see Graphics.Rendering.Diagrams.Query)

type DownAnnots v = Split (Transformation v) ::: (Style ::: (AM [] Name ::: Nil))Source

Monoidal annotations which travel down the diagram tree, i.e. which accumulate along each path to a leaf (and which can act on the upwards-travelling annotations):

- transformations (split at the innermost freeze): see Graphics.Rendering.Diagrams.Transform
- styles (see Graphics.Rendering.Diagrams.Style)
- names (see Graphics.Rendering.Diagrams.Names)

newtype AnnDiagram b v m Source

The fundamental diagram type is represented by trees of primitives with various monoidal annotations.

Functor (AnnDiagram b v) | |

(HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => Monoid (AnnDiagram b v m) | Diagrams form a monoid since each of their components do: the empty diagram has no primitives, a constantly zero bounding function, no named points, and a constantly empty query function. Diagrams compose by aligning their respective local origins. The new diagram has all the primitives and all the names from the two diagrams combined, and query functions are combined pointwise. The first diagram goes on top of the second. "On top of" probably only makes sense in vector spaces of dimension lower than 3, but in theory it could make sense for, say, 3-dimensional diagrams when viewed by 4-dimensional beings. |

(HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => HasStyle (AnnDiagram b v m) | |

(HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => HasOrigin (AnnDiagram b v m) | Every diagram has an intrinsic "local origin" which is the basis for all combining operations. |

(HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => Qualifiable (AnnDiagram b v m) | Diagrams can be qualified so that all their named points can now be referred to using the qualification prefix. |

(HasLinearMap v, OrderedField (Scalar v), InnerSpace v, Monoid m) => Transformable (AnnDiagram b v m) | Diagrams can be transformed by transforming each of their components appropriately. |

(HasLinearMap v, InnerSpace v, OrderedField (Scalar v)) => Boundable (AnnDiagram b v m) |

mkAD :: Prim b v -> Bounds v -> NameMap v -> Query v m -> AnnDiagram b v mSource

Create a diagram from a single primitive, along with a bounding region, name map, and query function.

type Diagram b v = AnnDiagram b v AnySource

The default sort of diagram is one where sampling at a point
simply tells you whether that point is occupied or not.
Transforming a default diagram into one with more interesting
annotations can be done via the `Functor`

instance of

.
`AnnDiagram`

b

# Operations on diagrams

## Extracting information

prims :: (HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => AnnDiagram b v m -> [(Prim b v, (Split (Transformation v), Style))]Source

Extract a list of primitives from a diagram, together with their associated transformations and styles.

bounds :: (OrderedField (Scalar v), InnerSpace v, HasLinearMap v) => AnnDiagram b v m -> Bounds vSource

Get the bounds of a diagram.

names :: HasLinearMap v => AnnDiagram b v m -> NameMap vSource

Get the name map of a diagram.

query :: (HasLinearMap v, Monoid m) => AnnDiagram b v m -> Query v mSource

Get the query function associated with a diagram.

sample :: (HasLinearMap v, Monoid m) => AnnDiagram b v m -> Point v -> mSource

Sample a diagram's query function at a given point.

## Combining diagrams

For many more ways of combining diagrams, see Diagrams.Combinators from the diagrams-lib package.

atop :: (HasLinearMap v, OrderedField (Scalar v), InnerSpace v, Monoid m) => AnnDiagram b v m -> AnnDiagram b v m -> AnnDiagram b v mSource

A convenient synonym for `mappend`

on diagrams, designed to be
used infix (to help remember which diagram goes on top of which
when combining them, namely, the first on top of the second).

## Modifying diagrams

named :: forall v b n m. (IsName n, HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => n -> AnnDiagram b v m -> AnnDiagram b v mSource

Attach a name to a diagram.

withName :: HasLinearMap v => Name -> (Point v -> AnnDiagram b v m -> AnnDiagram b v m) -> AnnDiagram b v m -> AnnDiagram b v mSource

Given a name and a diagram transformation indexed by a point, perform the transformation using the first point associated with the name, or perform the identity transformation if the name does not exist.

freeze :: forall v b m. (HasLinearMap v, InnerSpace v, OrderedField (Scalar v), Monoid m) => AnnDiagram b v m -> AnnDiagram b v mSource

By default, diagram attributes are not affected by
transformations. This means, for example, that `lw 0.01 circle`

and `scale 2 (lw 0.01 circle)`

will be drawn with lines of the
*same* width, and `scaleY 3 circle`

will be an ellipse drawn with
a uniform line. Once a diagram is frozen, however,
transformations do affect attributes, so, for example, ```
scale 2
(freeze (lw 0.01 circle))
```

will be drawn with a line twice as
thick as `lw 0.01 circle`

, and `scaleY 3 (freeze circle)`

will be
drawn with a "stretched", variable-width line.

Another way of thinking about it is that pre-`freeze`

, we are
transforming the "abstract idea" of a diagram, and the
transformed version is then drawn; when doing a `freeze`

, we
produce a concrete drawing of the diagram, and it is this visual
representation itself which is acted upon by subsequent
transformations.

# Primtives

Ultimately, every diagram is essentially a collection of
*primitives*, basic building blocks which can be rendered by
backends. However, not every backend must be able to render every
type of primitive; the collection of primitives a given backend
knows how to render is determined by instances of `Renderable`

.

A value of type `Prim b v`

is an opaque (existentially quantified)
primitive which backend `b`

knows how to render in vector space `v`

.

Prim :: Renderable t b => t -> Prim b (V t) |

HasLinearMap v => Transformable (Prim b v) | The |

HasLinearMap v => Renderable (Prim b v) b | The |

nullPrim :: (HasLinearMap v, Monoid (Render b v)) => Prim b vSource

The null primitive, which every backend can render by doing nothing.

# Backends

class (HasLinearMap v, Monoid (Render b v)) => Backend b v whereSource

Abstract diagrams are rendered to particular formats by
*backends*. Each backend/vector space combination must be an
instance of the `Backend`

class. A minimal complete definition
consists of the three associated types and implementations for
`withStyle`

and `doRender`

.

The type of rendering operations used by this backend, which
must be a monoid. For example, if `Render b v = M ()`

for some
monad `M`

, a monoid instance can be made with ```
mempty = return
()
```

and `mappend = (>>)`

.

The result of running/interpreting a rendering operation.

Backend-specific rendering options.

:: b | Backend token (needed only for type inference) |

-> Style | Style to use |

-> Transformation v | Transformation to be applied to the style |

-> Render b v | Rendering operation to run |

-> Render b v | Rendering operation using the style locally |

Perform a rendering operation with a local style.

:: b | Backend token (needed only for type inference) |

-> Options b v | Backend-specific collection of rendering options |

-> Render b v | Rendering operation to perform |

-> Result b v | Output of the rendering operation |

`doRender`

is used to interpret rendering operations.

adjustDia :: Monoid m => b -> Options b v -> AnnDiagram b v m -> AnnDiagram b v mSource

`adjustDia`

allows the backend to make adjustments to the final
diagram (e.g. to adjust the size based on the options) before
rendering it. A default implementation is provided which makes
no adjustments.

renderDia :: (InnerSpace v, OrderedField (Scalar v), Monoid m) => b -> Options b v -> AnnDiagram b v m -> Result b vSource

Render a diagram. This has a default implementation in terms
of `adjustDia`

, `withStyle`

, `doRender`

, and the `render`

operation from the `Renderable`

class (first `adjustDia`

is
used, then `withStyle`

and `render`

are used to render each
primitive, the resulting operations are combined with
`mconcat`

, and the final operation run with `doRender`

) but
backends may override it if desired.

class Backend b v => MultiBackend b v whereSource

A class for backends which support rendering multiple diagrams, e.g. to a multi-page pdf or something similar.

renderDias :: b -> Options b v -> [AnnDiagram b v m] -> Result b vSource

Render multiple diagrams at once.

# Renderable

class Transformable t => Renderable t b whereSource

The Renderable type class connects backends to primitives which they know how to render.

render :: b -> t -> Render b (V t)Source

Given a token representing the backend and a transformable object, render it in the appropriate rendering context.

(HasLinearMap v, Monoid (Render b v)) => Renderable (NullPrim v) b | |

HasLinearMap v => Renderable (Prim b v) b | The |