vgfx.h

Go to the documentation of this file.

/*
 * vgfx.h
 *
 * Copyright (C) 2007  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Vector graphics library.
 */

#ifndef WAVEPACKET_VGFX__H_
#define WAVEPACKET_VGFX__H_

// includes --------------------------------------------------------------------
#include <sstream>

#include "bezier/bezier.h"
#include "bezier/quad.h"
#include "objtree/objtree.h"    // TODO: do I want an objtree dependency here???
#include "geometry/xform_2d.h"
#include "util/parsing.h"


// namespace
namespace vgfx {


////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup  lib
/// \defgroup vgfx Vector Graphics Engine
///
/// vgfx is the Vector Graphics Engine.  It exists to represent the logical
/// model of nested, transformed 2D shapes.
///
/// The library is heavily optimized for two use cases:
///  - atomic, transactional updates (writes)
///  - very fast queries (reads)
///
/// In particular, the library doesn't try to be particularly fast on writes.
/// It is more concerned with correctness (of course), and with constructing a
/// rollback request for internal and external use.
///
/// Because any write operation returns a corresponding rollback request, it is
/// easy for calling applications to set up an undo/redo stack.
///
/// The request language is intended to be human-readable and easy for
/// applications to generate on the fly.  Think of something like SQL updates.
///
/// Queries are focused on either lookups by object ID, or lookups based on a
/// 2D rectangle.  Reads (queries) are intended to be fast so the engine can
/// be used in a real-time rendering application.
///
/// Typical client usage is:
///  - create an ObjectMap to represent your state
///  - construct requests (text statements) - see \ref vgfx_format
///  - call processRequest() to invoke requests on your ObjectMap
///             (this will populate and modify the map)
///  - call various ObjectMap or Primitive APIs to query the state of any
///             interesting objects.
///
/// If you want to draw any of this:
///  - provide an object that implements the vgfx::Drawer interface
///  - use the vgfx::Primitive::draw() method to recursively draw nested
///     object trees.
///
/// \n
/// Keep in mind: an ObjectMap isn't actually a canvas!  Think of it as a big
/// registry of objects which you can look up by name (ID).  And objects can
/// reference each other by their IDs.
///
/// To draw something, you have to provide an object to draw.  Typically an
/// application will create a bunch of objects in the ObjectMap, and then
/// put everything visible under a known root group object.  For display, the
/// application will call draw() on the root group object.  (To do this, the
/// application will have to create an object that implements the \ref Drawer
/// interface, and then call vgfx::Primitive::draw() on the root group
/// object).
///
/// \n
/// Other descriptions of vgfx (mostly for search engines):
///  - scriptable vector graphics engine
///  - transactional vector graphics engine
///  - queriable vector graphics engine
///  - programmable vector graphics engine
///
////////////////////////////////////////////////////////////////////////////////

/*@{*/


// typedefs
typedef point2d_t<float>        point_t;
typedef rect2d_t<float>         rect_t;

class ObjectMap;                        // forward declaration
class Primitive;
class Drawer;

/// hit detection results
enum eHitDetect {
        eHit_Overlap            = 1,    ///<- rects overlap at all
        eHit_Contained          = 2,    ///<- counts as a hit only if contained
        eHit_Always             = 3,    ///<- ignore rect, always hit

        eHit_Invalid            = 0
};


/// hit detection results
struct visit_result_t {
        // constructor, manipulators
        visit_result_t(void) throw() { this->clear(); }

        void clear(void) throw() {
                        p = NULL;
                        tag_path = NULL;
                        T.setIdentity();
                }

        // data fields
        Primitive *     p;              // pointer to current node
        const char *    tag_path;       // tag path to current node
        xform_2d_t      T;              // node local -> global coordinates
};


typedef bool (*callback_t)(IN void * context,
                                IN visit_result_t& result);


/// the base class from which all vector graphics objects inherit.
class Primitive {
public:
        // constructor, destructor ---------------------------------------------
        Primitive(void) throw();
        virtual ~Primitive(void) throw();

        // vgfx::Primitive ref counting methods (all primitives get these) -----
        virtual long getRefCount(void) const throw() { return m_refcount; }
        virtual void incrementRefCount(void) throw() {
                        ++m_refcount;
                //      DPRINTF("Incrementing ref count for object '%s': %ld",
                //          this->getID(), m_refcount);
                }
        virtual void decrementRefCount(void) throw() {
                        --m_refcount;
                //      DPRINTF("Decrementing ref count for object '%s': %ld",
                //          this->getID(), m_refcount);
                        ASSERT(m_refcount >= 0,
                            "Bad ref count: %ld", m_refcount);
                 }

        // vgfx::Primitive class interface methods -----------------------------
        virtual const char * getID(void) const throw();
        virtual void setID(IN const char * id);
        virtual const char * getType(void) const throw() = 0;
        virtual void persist(OUT std::ostream& stream) const = 0;
        virtual void listContainers(IN const VecString& path,
                                OUT VecString& ids) const;
        virtual bool doesContainerExist(IN const VecString& path) const;
        virtual bool canCreateContainer(IN const VecString& path) const;
        virtual void removeContainer(IN const VecString& path);
        virtual void getContainerDictionary(IN const VecString& path,
                                OUT dictionary_t& data) const;
        virtual void setContainerDictionary(IN const VecString& path,
                                IN const dictionary_t& data);
        virtual void recalcBoundingRect(IN const char * tag_path,
                                IN Drawer * drawer,
                                IN const xform_2d_t& T) = 0; //<- local -> drawer
        virtual bool getBoundingRect(OUT rect_t& r) const throw() = 0;
        virtual bool getPrimitive(IN const char * tag_path,
                                IN const xform_2d_t& T,      //<- local -> global
                                OUT visit_result_t& vr);

        /// draw this primitive and all children, recursively
        virtual void draw(IN Drawer * drawer,
                                IN const rect_t& r_pix,      //<- absolute
                                IN const xform_2d_t& T) = 0; //<- local -> drawer
        virtual bool visit(IN const rect_t& r,          // global coords
                                IN const xform_2d_t& T, // local --> global
                                IN const char * tag_path,
                                IN callback_t callback,
                                IN void * context,
                                IN eHitDetect hit);

        // static factory methods ----------------------------------------------
        static smart_ptr<Primitive> create(IN const char * type,
                                IN const dictionary_t& data);

private:
        // private member data -------------------------------------------------
        long            m_refcount;
        std::string     m_id;
};



/// an ObjectMap is a physical manifestation of a vector graphics 2D area.
///
/// This is the state that contains all primitives.
///
/// It is recommended that you do NOT use these APIs to modify the map!
/// Use vgfx::processRequest() instead.
class ObjectMap {
public:
        // virtual destructor --------------------------------------------------
        virtual ~ObjectMap(void) throw();

        // vgfx::ObjectMap class interface methods -----------------------------
        virtual long size(void) const throw() = 0;
        virtual void newObjectID(IN const char * prefix,
                                OUT std::string& id) = 0;
        virtual void addObject(IN smart_ptr<Primitive>& primitive) = 0;
        virtual Primitive * findObject(IN const char * ID) const throw() = 0;
        virtual smart_ptr<Primitive> removeObject(IN const char * ID) = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<ObjectMap> create(void);
};



////////////////////////////////////////////////////////////////////////////////
//
//      Parsing functions
//
////////////////////////////////////////////////////////////////////////////////

/// Request that an ObjectMap be updated with the given request.
///
/// Returns false on failure.
///
/// \param map ObjectMap upon which the request will act.
/// \param stream Input text stream containing request.  See \ref vgfx_format.
/// \param single_transaction If true, the request will be handled as an
///     atomic operation and an undo request will be returned.  If false, there
///     is no rollback of partial commits.  Use true unless you have good reason
///     otherwise.
/// \param undo_request On output, this contains a request which will undo the
///     original input request.  Handy for undo/redo stacks.
/// \param diagnostic If the return value is false, this string will contain
///     some details on output which may be helpful in tracking down what
///     failed.
bool processRequest(IN ObjectMap * map, 
                                IN std::istream& stream,
                                IN bool single_transaction,
                                OUT std::string& undo_request,
                                OUT std::string& diagnostic);



////////////////////////////////////////////////////////////////////////////////
//
//      Function objects
//
////////////////////////////////////////////////////////////////////////////////

// raw invocation (returns partial request)
void invokeFunction(IN Primitive * function,
                                IN ObjectMap * map,
                                IN const dictionary_t& in_params,
                                OUT std::ostream& stream);

// better helper methods

// addFunctionFromPath(map, path) - given a filesystem path, checks to see
//   if we already have this function loaded, and if not, loads it and adds
//   it to the map
//   either way, the function returns a pointer to the Function object
Primitive * addFunctionFromPath(IN ObjectMap * map,
                                IN const char * path);


// setScript(map, parent, script, stream) - updates stream with instructions
//   to add a script parameter group, and a child group which has the script
//   results.  Also returns ID of root script parameter object.
void setScript(IN ObjectMap * map,
                                IN const char * parent_id,
                                IN const char * script_id,
                                IN const objtree::property_set_t& defaults,
                                IO std::ostream& stream,
                                OUT std::string& root_id);

// updateScriptParameters(map, parent, pset, stream) - updates stream with
//   instructions to update script parameters, and re-run the child script
void updateScriptParameters(IN ObjectMap * map,
                                IN const char * parent_id,
                                IN const objtree::property_set_t& pset,
                                IO std::ostream& stream);

// resizeScript(map, parent, width, height, stream) - updates stream with script
//      having re-run given new size
void resizeScript(IN ObjectMap * map,
                                IN const char * parent_id,
                                IN float width,
                                IN float height,
                                IO std::ostream& stream);


// helpful for objects
template <class T>
std::string getStringValue(const T& t)
{
        std::ostringstream out;
        out << t;
        return out.str();
}



////////////////////////////////////////////////////////////////////////////////
//
//      Vector Graphics Primitives (vgfx primitives)
//
//      This just declares factories with necessary input data.
//      A naming scheme is carefully followed to make use of macros easier.
//
//      Clients don't normally need these, although it does give you the power
//      to directly create primitives outside of the parser, either using
//      parser-like data or with custom data structures.
//
////////////////////////////////////////////////////////////////////////////////

// base initialization struct for all primitives
struct init_primitive_t {
        std::string     id;
};


// point
struct init_point_t : public init_primitive_t {
        float x0;
        float y0;
};

void init_point_from_data(IN const dictionary_t& data,
                                OUT init_point_t&);
smart_ptr<Primitive> create_point(IN const init_point_t&);


// bezier
struct init_bezier_t : public init_primitive_t {
        bezier::curve_t         curve;
};

void init_bezier_from_data(IN const dictionary_t& data,
                                OUT init_bezier_t&);
smart_ptr<Primitive> create_bezier(IN const init_bezier_t&);


// rect
struct init_rect_t : public init_primitive_t {
        rect_t                  rect;
        bool                    fill;   // fill rect when drawing?
};

void init_rect_from_data(IN const dictionary_t& data,
                                OUT init_rect_t&);
smart_ptr<Primitive> create_rect(IN const init_rect_t&);


// line
struct init_line_t : public init_primitive_t {
        float                   x0;
        float                   y0;
        float                   x1;
        float                   y1;
};

void init_line_from_data(IN const dictionary_t& data,
                                OUT init_line_t&);
smart_ptr<Primitive> create_line(IN const init_line_t&);


// dxdy
struct init_dxdy_t : public init_primitive_t {
        float                   dx;
        float                   dy;
};

void init_dxdy_from_data(IN const dictionary_t& data,
                                OUT init_dxdy_t&);
smart_ptr<Primitive> create_dxdy(IN const init_dxdy_t&);


// quad (quadratic bezier)
struct init_quad_t : public init_primitive_t {
        bezier::quad_bezier_t   quad;
};

void init_quad_from_data(IN const dictionary_t& data,
                                OUT init_quad_t&);
smart_ptr<Primitive> create_quad(IN const init_quad_t&);


// group
smart_ptr<Primitive> parseGroup(IN std::istream& stream,
                                IN ObjectMap * map);

// function
smart_ptr<Primitive> parseFunction(IN std::istream& stream,
                                IN ObjectMap * map);


// text
struct init_text_t : public init_primitive_t {
        std::string     text;
};

void init_text_from_data(IN const dictionary_t& data,
                                OUT init_text_t&);
smart_ptr<Primitive> create_text(IN const init_text_t&);


};      // vgfx primitives


#endif  // WAVEPACKET_VGFX__H__