main.doxy

Go to the documentation of this file.

/*!
  \file main.doxy
  \brief main.doxy
 */

/*!
\defgroup Utility Utility
@{
\brief
Utility provides simple utility classes, the most important and
commonly used ones being \ref reference_counted_ptr, \ref vecN,
and \ref c_array. Part of the main library libFastUIDraw.
@}

\defgroup Glyph Glyph
@{
\brief
\ref Glyph provides the interfaces to realizing glyph data for rendering
glyphs. The big classes being \ref Glyph, \ref GlyphCache, \ref
GlyphAtlas and \ref FontBase. Part of the main library libFastUIDraw.
@}

\defgroup Paths Paths
@{
\brief
Path provides the interface to realize paths, the main entry point
for applications is the object \ref Path.
@}

\defgroup Imaging Imaging
@{
\brief
Imaging provides the interface to realize images
and color gradients.
@}

\defgroup GLSL GLSL
@{
\brief
Utility module to assist in creating GLSL shaders and also provides
\ref fastuidraw::glsl::PainterShaderRegistrarGLSL which provides
shader assembly and default shaders via GLSL shaders. The GL backend
via the class \ref fastuidraw::gl::PainterEngineGL builds off of
\ref fastuidraw::glsl::PainterShaderRegistrarGLSL in that its
\ref fastuidraw::PainterEngine::painter_shader_registrar() method
returns an object derived from \ref fastuidraw::glsl::PainterShaderRegistrarGLSL.
Part of the main library libFastUIDraw.
@}

\defgroup GLSLVertFragCode GLSL Vertex Fragment Code
@{
\brief
This group documents the GLSL functions fastuidraw makes available
to GLSL code fragments for both vertex and fragment shading for
custom shading as embodied by the classes \ref
fastuidraw::glsl::PainterItemShaderGLSL, \ref
fastuidraw::glsl::PainterBlendShaderGLSL and \ref
fastuidraw::glsl::PainterBrushShaderGLSL.
@}

\defgroup GLSLVertCode GLSL Vertex Code
@{
\brief
This group documents the GLSL functions fastuidraw makes available
to GLSL code fragments for only vertex shading for custom shading
as embodied by the classes \ref fastuidraw::glsl::PainterItemShaderGLSL,
\ref fastuidraw::glsl::PainterBlendShaderGLSL and \ref
fastuidraw::glsl::PainterBrushShaderGLSL.
@}

\defgroup GLSLFragCode GLSL Fragment Code
@{
\brief
This group documents the GLSL functions fastuidraw makes available
to GLSL code fragments for only fragment shader for custom shading
as embodied by the classes \ref fastuidraw::glsl::PainterItemShaderGLSL,
\ref fastuidraw::glsl::PainterBlendShaderGLSL and \ref
fastuidraw::glsl::PainterBrushShaderGLSL.
@}

\defgroup GLSLBuiltInShaders GLSL Built in Shaders
@{
\brief
This group documents the symbols and varyings of the built in shaders
provided by the GLSL module (which is used by both the GL and GLES
backends.

The following symbols are available as keyed by the values within
a \ref fastuidraw::PainterShaderSet.

For \ref fastuidraw::PainterShaderSet::stroke_shader() and each \ref
fastuidraw::PainterStrokeShader of \ref fastuidraw::PainterShaderSet::dashed_stroke_shader(),
there is the following. For the vertex shaders there are the public symbols:
- fastuidraw_stroking_distance gives the distance from the start of the contour along the path
- fastuidraw_stroking_contour_length gives the length of the contour
- fastuidraw_stroking_edge_length gives the length of the edge
- fastuidraw_stroking_edge_start gives how far along the path the start of the edge is
The non anti-aliased shaders (i.e. \ref fastuidraw::PainterStrokeShader::non_aa_shader),
have the following symbols in the fragment shader exposed:
- fastuidraw_stroking_distance the distance from the start of the contour along the path
- fastuidraw_stroking_distance_fwidth fwidth of fastuidraw_stroking_distance. Use this value to
                                      perform anti-aliasing coverage computations
- fastuidraw_stroking_relative_distance_from_center this value is 0.0 on the path and grows to 1.0
                                                    at the stroking boundary
- fastuidraw_stroking_distance_fwidth fwidth of fastuidraw_stroking_relative_distance_from_center.
                                       Use this value to perform anti-aliasing coverage computations
The anti-aliasing shaders (i.e. \ref fastuidraw::PainterStrokeShader::aa_shader) are two pass
shaders where the coverage shader (i.e. \ref fastuidraw::PainterItemShader::coverage_shader()) has
the above symbols in fragment shader (and also the vertex symbols in the vertex shader), but the
item shader only has the vertex shader symbols but not the fragment shader symbols.

Each shader present in \ref fastuidraw::PainterShaderSet::brush_shaders() has the two varyings:
- fastuidraw_brush_p_x which gives the x-coordinate of the brush
- fastuidraw_brush_p_y which gives the y-coordinate of the brush
The \ref fastuidraw::PainterGradientBrushShader::linear_sub_shader() has the varyings:
- fastuidraw_brush_gradient_p0_x the x-coordinate of the start position of the linear gradient
- fastuidraw_brush_gradient_p0_y the y-coordinate of the start position of the linear gradient
- fastuidraw_brush_gradient_p1_x the x-coordinate of the end position of the linear gradient
- fastuidraw_brush_gradient_p1_y the y-coordinate of the end position of the linear gradient
The \ref fastuidraw::PainterGradientBrushShader::radial_sub_shader() has the varyings:
- fastuidraw_brush_gradient_p0_x the x-coordinate of the start position of the radial gradient
- fastuidraw_brush_gradient_p0_y the y-coordinate of the start position of the radial gradient
- fastuidraw_brush_gradient_r0 the start radius of the radial gradient
- fastuidraw_brush_gradient_p1_x the x-coordinate of the end position of the radial gradient
- fastuidraw_brush_gradient_p1_y the y-coordinate of the end position of the radial gradient
- fastuidraw_brush_gradient_r1 the end radius of the radial gradient
The \ref fastuidraw::PainterGradientBrushShader::sweep_sub_shader() has the varyings:
- fastuidraw_brush_gradient_sweep_point_x the x-coordinate of the sweep point
- fastuidraw_brush_gradient_sweep_point_y the y-coordinate of the sweep point
- fastuidraw_brush_gradient_sweep_angle the start angle of the sweep gradient
- fastuidraw_brush_gradient_sweep_sign_factor the signed multiplier of the sweep gradient.
The \ref fastuidraw::PainterGradientBrushShader::sub_shader() has all of the above varyings
(since it encompasses all of the gradients) either directly or realized as aliases.

The standard brush, \ref fastuidraw::PainterBrushShaderSet::standard_brush(), is itself
realized as a chain shader with the image of the brush accessible via its dependee named
image_brush, and the gradient via the dependee name gradient_brush.


@}

\defgroup Painter Painter
@{
\brief
Painter provides the interface for Canvas drawing, the most important class
being Painter. Part of the main library libFastUIDraw.
@}

\defgroup PainterAttribute Painter Attribute
@{
\brief
Painter Attribute provides the interface to define the attribute data
to be used by shaders. This includes how glyphs, stroked paths and filled
paths are realized as attribute data.

The class \ref fastuidraw::PainterAttribute represents a single attribute
(the what to draw). FastUIDraw works -exclusively- in drawing triangles
and the indices of the what to draw are realized as \ref fastuidraw::PainterIndex.
The class \ref fastuidraw::PainterAttributeData represents a collection
of attribute and indices to draw.

If the attribute and/or index data needs to be dynamic (but the CPU cost
should be low), the class \ref fastuidraw::PainterAttributeWriter
can be used. One example of its use is \ref fastuidraw::GlyphRun which
uses it to select what sub-range of indices to feed to draw only a portion
of text.
@}

\defgroup PainterShaders Painter Shaders
@{
\brief
\ref PainterShaders defines the interface how to specify shaders used by
\ref Painter to render items.

There are four types of shaders
- \ref fastuidraw::PainterItemShader represents the shader code to
  perform vertex and fragment processing on an item.
- \ref fastuidraw::PainterBrush and \ref fastuidraw::PainterCustomBrush
  represent the shader code to compute the color that that brush
  applies
- \ref fastuidraw::PainterBlendShader represents the shader code to
  perform blending.
- \ref fastuidraw::PainterItemCoverageShader is an auxiliary shader
  that can be used by a \ref fastuidraw::PainterItemShader to compute
  a coverage value for the purpose of two-pass rendering.

Each of these shaders can fetch shader-data to modify their processing
(for example an item shader for stroking a path would fetch the stroking
width in the vertex shader). The classes for realizing the shader-data
are
- \ref fastuidraw::PainterItemShaderData for both \ref fastuidraw::PainterItemShader
  and \ref fastuidraw::PainterItemCoverageShader
- \ref fastuidraw::PainterBlendShaderData for \ref fastuidraw::PainterBlendShader
- \ref fastuidraw::PainterBrush for the built-in brush of FastUIDraw
- \ref fastuidraw::PainterBrushShaderData for \ref fastuidraw::PainterBrushShader
  for custom brushes

Each of these objects can be passed to a \ref fastuidraw::Painter drawing method
by address with the class \ref fastuidraw::PainterData. In addition, if a value
is to be reused in several drawing calls to \ref fastuidraw::Painter, one can use
the interface of \ref fastuidraw::PainterPackedValuePool (fetched from \ref
fastuidraw::Painter::packed_value_pool()) to realize a \ref fastuidraw::PainterPackedValue
which represents the value immutably packed for the GPU in such a way that its packing
into the GPU can be dramatically reused within a frame.
@}

\defgroup PainterShaderData Painter Shader Data
@{
\brief
\ref PainterShaderData defines the interface for providing
to shaders a small amount of data that is constant across
all vertices and pixels of a drawn item.

Each of the data classes is paired with a shader classes:
- \ref fastuidraw::PainterItemShaderData for both \ref fastuidraw::PainterItemShader
  and \ref fastuidraw::PainterItemCoverageShader
- \ref fastuidraw::PainterBlendShaderData for \ref fastuidraw::PainterBlendShader
- \ref fastuidraw::PainterBrush for the built-in brush of FastUIDraw
- \ref fastuidraw::PainterBrushShaderData for \ref fastuidraw::PainterBrushShader
  for custom brushes

The data is passed to \ref fastuidraw::Painter methods through the class
\ref fastuidraw::PainterData. Shader data can also be pre-packed by a
caller for reuse through the immutable class \ref fastuidraw::PainterPackedValue.
Using \ref fastuidraw::PainterPackedValue for when the same shader data values
are used is a big win because that class provides the means for
FastUIDraw to upload that shader data far fewer times (usually once for
an entire frame instead once per use).

@}

\defgroup PainterBackend Painter Backend
@{
\brief
If one is making a painter backend, then this group provides the
information, see particularly the enumerations in fastuidraw::PainterHeader,
fastuidraw::PainterItemMatrix, fastuidraw::PainterClipEquations
for how data is packed by fastuidraw::Painter. Part of the main library
libFastUIDraw.

\section Overview
The class fastuidraw::Painter implements canvas rendering using an implementation
of the backend interface fastuidraw::PainterBackend to send data to a 3D API.
The class fastuidraw::Painter packs data that is used by multiple triangles
into fastuidraw::PainterDrawCommand::m_store (for example the current transformation).
In implementing a backend, the shader fed to the GPU needs to correctly unpack
this data. The location of the header of the data is stored in the attribute
from the value fastuidraw::PainterDrawCommand::m_header_attributes. The header
consists of fastuidraw::PainterHeader::header_size uint32_t values whose location
relative to the start of the header and meaning are enumerated by
fastuidraw::PainterHeader::offset_t. The header contains shader ID's
and additional offsets to more data packed for a shader to unpack.

@}

\defgroup GLBackend GL Backend
@{
\brief
Implementation of a backend using the OpenGL (or OpenGL ES) GPU API.
@}

\defgroup GLUtility GL Utility
@{
\brief
Collection of utility interfaces used by \ref GLBackend that an application
may wish to use as well.
@}
*/

/*!
  \brief all classes and functions of FastUIDraw are in the
         namespace fastuidraw.
 */
namespace fastuidraw {

/*!\addtogroup GLSL
  @{
 */
  /*!
    \brief Namespace to encapsulate shader building to GLSL
           shaders, part of the main library libFastUIDraw.
   */
  namespace glsl
  {
  }
/*! @} */

  /*!
    \brief Namespace to encapsulate GL backend end implementation,
    utility functions and utility classes. Part of the GL
    backend libraries, libFastUIDrawGL and libFastUIDrawGLES.
  */
  namespace gl
  {

/*!\addtogroup GLUtility
  @{
 */
    /*!
      \brief Template version for setting an of uniform values
      \param location location of uniform, i.e. return value
             of glGetUniformLocation
      \param v array of values
      \param count number of elements from the array v to use.
    */
    template<typename T>
    void
    Uniform(int location, GLsizei count, const T *v);

    /*!
      \brief Template version for setting an array of matrix uniform values.
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
      \param v value
      \param count number of elements from the array v to use.
      \param transposed set to tue true if GL should interpret the matrices as transposed
    */
    template<typename T, size_t N, size_t M>
    void
    Uniform(int location, GLsizei count, const matrixNxM<T, N, M> *v, bool transposed = false);

    /*!
      \brief Template version for setting a single uniform value.
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
                      \param v value
    */
    template<typename T, size_t N>
    void
    Uniform(int location, const vecN<T, N> &v);

    /*!
      \brief Template version for setting a single matrix uniform value.
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
      \param v value
      \param transposed set to tue true if GL should interpret the matrices as transposed
    */
    template<typename T, size_t N, size_t M>
    void
    Uniform(int location, const matrixNxM<T, N, M> &v, bool transposed = false);

    /*!
      \brief Template version for setting an of uniform values
      \param program GL name of program to which uniform(s) belong
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
      \param v array of values
      \param count number of elements from the array v to use.
    */
    template<typename T>
    void
    ProgramUniform(GLuint program, int location, GLsizei count, const T *v);

    /*!
      \brief Template version for setting an array of matrix uniform values.
      \param program GL name of program to which uniform(s) belong
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
      \param v value
      \param count number of elements from the array v to use.
      \param transposed set to tue true if GL should interpret the matrices as transposed
    */
    template<typename T, size_t N, size_t M>
    void
    ProgramUniform(GLuint program, int location, GLsizei count, const matrixNxM<T, N, M> *v, bool transposed = false);

    /*!
      \brief Template version for setting a single uniform value.
      \param program GL name of program to which uniform(s) belong
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
      \param v value
    */
    template<typename T, size_t N>
    void
    ProgramUniform(GLuint program, int location, const vecN<T, N> &v);

    /*!
      \brief Template version for setting a single matrix uniform value.
      \param program GL name of program to which uniform(s) belong
      \param location location of uniform, i.e. return value
                      of glGetUniformLocation
      \param v value
      \param transposed set to tue true if GL should interpret the matrices as transposed
    */
    template<typename T, size_t N, size_t M>
    void
    ProgramUniform(GLuint program, int location, const matrixNxM<T, N, M> &v, bool transposed = false);

    /*! @} */
  }
}

/*! \mainpage FastUIDraw

  \section Purpose

  FastUIDraw is a library that provides a higher performance Canvas interface.
  It is designed so that it always draws using a GPU.

  In contrast to many common implementations of Canvas drawing, FastUIDraw
  has that changes in clipping are very cheap and optimized for GPU's. In
  addition, FastUIDraw has, with the GL backend, very few pipeline states.
  Indeed an API trace of an application using FastUIDraw will see only a
  handful of draw calls per frame, even under high Canvas state trashing,
  and high clip state changes. Indeed, for the GL backend, only one Canvas
  state change invokes a pipeline state change: changing the blend mode.

  The class to execute drawing is \ref fastuidraw::Painter which supplies
  the expected standard drawing features: stroking and filling paths,
  drawing text, applying a brush (image and/or gradient), blending (including
  all Porter-Duff modes), a 3x3 transformation allowing for perspective
  drawing, clipping in by a rectangle or filled path and clipping out by
  a filled path.

  In addition, FastUIDraw gives an application the ability to make their
  own shaders for custom drawing.

  \section Drawing Concepts

  If one needs to create its own custom way of drawing, one needs
  to know the drawing concepts in FastUIDraw. There are three distinct
  ingredients of drawing in FastUIDraw:
  - Attribute and index data processed by the GPU. This data should be
    immutable to be created/calculated once and reused greatly.
    At the very bottom of this stack is \ref fastuidraw::PainterIndex
    to represent an index and \ref fastuidraw::PainterAttribute to
    represent an attribute. A \ref fastuidraw::PainterAttributeData
    represents a collection of attribute and index chunks. The classes,
    \ref fastuidraw::StrokedPath, \ref fastuidraw::FilledPath, \ref
    fastuidraw::GlyphRun and \ref fastuidraw::GlyphSequence hold \ref
    fastuidraw::PainterAttributeData objects ready for drawing. For
    futher reading, see \ref PainterAttribute.
  - The shader to draw the attribute and index data. FastUIDraw has
    three shader types in its vertex and fragment pipeline (defined
    in the module \ref PainterShaders).
    - An item shader is represented by \ref fastuidraw::PainterItemShader.
      This shader represents how the attribute and index data are
      processed.
    - A brush shader is represented by \ref fastuidraw::PainterBrushShader.
      This shader represents computing a per-pixel color, for example
      an image or gradient applied.
    - A blend shader is represented by \ref fastuidraw::PainterBlendShader.
      This shader represents how blending is performed (for example the
      Porter-Duff modes).
  - A small amount of data that is cheap to recalculate that is constant
    for all vertices and pixels of an item. Each of the shader stages has
    their own data classes (defined in the module \ref PainterShaderData).
    - For item shading, the class \ref fastuidraw::PainterItemShaderData
      is used to hold values that are constant for all attributes across
      an item. One example are stroking paremeters such as stroking
      width and miter-limit to apply to stroking as realized by \ref
      fastuidraw::PainterStrokeParams and \ref fastuidraw::PainterDashedStrokeParams.
    - For brush shading, the class \ref fastuidraw::PainterBrushShaderData
      is used to hold values that are constant for the purpose of appliying
      a brush. The main example is \ref fastuidraw::PainterBrush which holds
      all the data needed to apply a standard brush consisting of an image,
      gradient, repeat pattern and brush transformation.
    - For blend shading, the class \ref fastuidraw::PainterBlendShaderData
      is used to hold constants values for doing blending.

  The GL/GLES backends of FastUIDraw represents shaders as portions of GLSL
  shader code, see the classes \ref fastuidraw::glsl::PainterItemShaderGLSL,
  \ref fastuidraw::glsl::PainterBlendShaderGLSL and \ref
  fastuidraw::glsl::PainterBrushShaderGLSL for the shader class types and their
  interfaces.

  \section Examples
  - See \ref ex_framework for the example framework to get started with the examples.
  - See \ref ex_initialization for the how to create a \ref fastuidraw::Painter.
  - See \ref ex_text for an example of using \ref fastuidraw::GlyphSequence to draw text with \ref fastuidraw::Painter.
  - See \ref ex_gradient for an example of using \ref fastuidraw::PainterBrush to render gradients.
  - See \ref ex_image for an example of using \ref fastuidraw::PainterBrush to render an image.
  - See \ref ex_custom_brush for an example of creating a custom brush
  - See \ref ex_path for an example of using \ref fastuidraw::Path to stroke and fill paths.
  - See \ref ex_path2 for creating a \ref fastuidraw::Path with the operator<< overloads and filling it with a custom fill rule.
  - See \ref ex_packed_value for an example of using \ref fastuidraw::PainterPackedValue and coordinate transformations of \ref fastuidraw::Painter.
  - See \ref ex_custom_stroking_shader for an example of using shader chaining to create an animated wave-effect of stroking via shader chaining
*/