p_group.cpp

Go to the documentation of this file.

/*
 * p_group.cpp
 *
 * Copyright (C) 2007,2009,2010   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.
 *
 *
 * Implementation of the group primitive.
 */

// includes --------------------------------------------------------------------
#include "vgfx.h"               // always include our own header first!
#include "drawer.h"

#include <istream>
#include <sstream>

#include "bezier/fit.h"
#include "common/wave_ex.h"
#include "objtree/objtree.h"    // for isValidPropertyName() only!
#include "perf/perf.h"
#include "util/parsing.h"
#include "util/token_stream.h"


// typedefs and constants ------------------------------------------------------

namespace vgfx {


static const eParseBehavior s_line_behavior     = (eParseBehavior) (
        eParse_StripComments |
        eParse_StripBogus |
        eParse_RespectQuotes
        );


enum eGroupType {
        eGT_Normal              = 1,
        eGT_Path                = 2,

        eGT_Invalid             = 0
};



struct brush_entry_t {
        const char *            key;    // meta key name to look for
        eBrushAttribute         attrib; // brush attribute to set
};


#define BRUSH_ENTRY(key, attrib) { "vgfx" #key , eBrush_ ##attrib },

static const brush_entry_t s_brushTable[] = {
        BRUSH_ENTRY(Color,              PenColor)
        BRUSH_ENTRY(FillColor,          FillColor)
        BRUSH_ENTRY(Thickness,          PenThickness)
        BRUSH_ENTRY(Font,               Font)
        BRUSH_ENTRY(TextFlags,          TextFlags)

        // must be last!
        { NULL, eBrush_Invalid }
};



static dword_t
getDwordFromPointer
(
IN void * ptr
)
throw()
{
        // ASSERT(ptr) -- can be null
        const dword_t * pdw = (const dword_t *) &ptr;
        return *pdw;
}



static int
getPathElement
(
IN const char * path,
IO char * buffer,
IN int bufsize
)
{
        ASSERT(path, "null path");
        ASSERT(buffer, "null");
        ASSERT(bufsize > 1, "bad buffer size: %d", bufsize);

        // special case
        if (!strcmp("*", path)) {
                buffer[0] = '*';
                buffer[1] = 0;
                return 0;
        }

        // skip the first character if it's a slash
        const char * start = path;
        if ('/' == *path)
                ++path;

        // look for next slash...
        int n = 0;
        while (n < bufsize && *path && '/' != *path) {
                buffer[n] = *path;
                ++path;
                ++n;
        }

        if (n >= bufsize)
                return -1;      // too big for buffer
        buffer[n] = 0;          // null-terminate

        if ('/' == *path)
                ++path;         // skip slash

        return path - start;
}



static void
updateBrush
(
IN const Dictionary& d,
IN Drawer * drawer
)
{
        ASSERT(drawer, "null");

        for (const brush_entry_t * p = s_brushTable; p->key; ++p) {

                const char * value = getValue(d, p->key);
                if (value) {
                        drawer->setBrushAttribute(p->attrib, value);
                }
        }
}




static void
adjustRefCount
(
IN ObjectMap * map,
IN const char * id,
IN long delta
)
{
        ASSERT(map, "null map");
        ASSERT(id, "null id");

        Primitive * p = map->findObject(id);
        if (!p) {
                if (delta > 0) {
                        WAVE_EX(wex);
                        wex << "Cannot reference object '" << id << "': it does not ";
                        wex << "exist.";
                }

                // when an entire map is going away, we can see cases where
                // an object goes away before its refs
                return;
        }

        if (+1 == delta) {
                p->incrementRefCount();
        } else if (-1 == delta) {
                p->decrementRefCount();
        } else {
                ASSERT(false, "bad ref count delta: %ld", delta);
        }
}



class ObjectRef {
public:
        // constructors, destructor --------------------------------------------
        ObjectRef(void) throw() : m_map(NULL), m_id("") { }
        ObjectRef(IN const ObjectRef& r) : m_map(NULL), m_id("") {
                        *this = r;
                }
        ~ObjectRef(void) {
                        // DPRINTF("ObjectRef destructor");
                        this->clear();
                }

        // accessors -----------------------------------------------------------
        const char * getID(void) const throw() { return m_id.c_str(); }
        void setID(IN ObjectMap * map, IN const char * id) {
                        ASSERT(map, "null");
                        ASSERT(id, "null");
                        this->clear();
                        m_map = map;
                        m_id = id;
                        if (m_id != "") {
                                adjustRefCount(m_map, id, +1);
                        }
                }
        void dump(IN const char * title) const throw() {
                        DPRINTF("  %s: map=%p  id='%s'",
                            title, m_map, m_id.c_str());
                }

        const ObjectRef& operator= (IN const ObjectRef& r) {
                        this->clear();
                        if (r.m_map) {
                                this->setID(r.m_map, r.getID());
                        }
                        return *this;
                }

private:

        void clear(void) {
                        if (m_map && m_id != "") {
                                adjustRefCount(m_map, m_id.c_str(), -1);
                        }
                        m_map = NULL;
                        m_id = "";
                }

        ObjectMap      *m_map;
        std::string     m_id;
};


struct object_t {
        void dump(IN const char * title) const throw() {
                        ref.dump(title);
                }
        const char * getTag(void) const throw() { return tag.c_str(); }
        void clear(void) throw() {
                        x = y = z = phi = 0.0;
                        scale = 1.0;
                        xform.clear();
                }

        // data fields
        ObjectRef       ref;    // id of object this refers to
        std::string     tag;    // tag of object reference
        float           x;      // position x-coordinate
        float           y;
        float           z;      // z-order: higher number is closer to user
        float           phi;    // rotation around z-axis
        float           scale;  // scaling (all axes)
        xform_2d_t      xform;  // transformation (translation, rotation, etc.)
};

//typedef std::map<std::string, object_t> map_obj_t;

// keep a list of objects in z-order
typedef std::multimap<float, object_t> map_obj_t;


////////////////////////////////////////////////////////////////////////////////
//
//      static helper methods
//
////////////////////////////////////////////////////////////////////////////////

static void
updateObjectTransform
(
IO object_t& obj
)
{
        // construct transformation
        // TODO: support rotations, other transformations!
        xform_2d_t translate;
        translate.setTranslate(obj.x, obj.y);

        xform_2d_t zrotate;
        zrotate.setZRotate(obj.phi);

        xform_2d_t temp;
        temp.setToProductOf(translate, zrotate);

        xform_2d_t scale;
        scale.setIdentity();
        scale.scale(obj.scale);

        obj.xform.setToProductOf(temp, scale);
}



////////////////////////////////////////////////////////////////////////////////
//
//      Group primitive type
//
////////////////////////////////////////////////////////////////////////////////

// TODO: pull the group out into a separate file!!!  It's not part of the parser
class Group : public Primitive {
public:
        Group(IN ObjectMap * map) throw();
        ~Group(void) throw(); 

        // public class methods ------------------------------------------------
        void addMeta(IN const char * key,
                                IN const char * value);
        void addObject(IN const object_t& obj);

        // vgfx::Primitive class interface methods -----------------------------
        virtual const char * getType(void) const throw() { return "group"; }
        virtual void persist(IO std::ostream& stream) const;
        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) throw();
        virtual bool getBoundingRect(OUT rect_t& r) const throw();
        virtual bool getPrimitive(IN const char * tag_path,
                                IN const xform_2d_t& T,
                                OUT visit_result_t& vr);
        virtual void draw(IN Drawer * drawer,
                                IN const rect_t& r_cm,
                                IN const xform_2d_t& T); // local --> absolute
        virtual bool visit(IN const rect_t& r,
                                IN const xform_2d_t& T,
                                IN const char * tag_path,
                                IN callback_t callback,
                                IN void * context,
                                IN eHitDetect hit);

private:
        // private helper methods ----------------------------------------------
        map_obj_t::iterator findObject(IN const char * tag) throw();
        map_obj_t::const_iterator findObject(IN const char * tag) const throw();
        void updateDrawer(IN Drawer * drawer,
                                IN const xform_2d_t& T);
        void expandPath(IN const char * path);
        void nukePath(void);

        // private member data -------------------------------------------------
        map_obj_t               m_objects;      // map of all objects
        Dictionary              m_meta;         // meta key/value pairs
        ObjectMap              *m_map;          // weak ref
        rect_t                  m_bounding;     // cached bounding rect
        eGroupType              m_type;         // what type of group?
        bool                    m_have_rect;    // have a bounding rect?
};



////////////////////////////////////////////////////////////////////////////////
//
//      Group constructor + destructor
//
////////////////////////////////////////////////////////////////////////////////

Group::Group
(
IN ObjectMap * map
)
throw() :
m_map(map),
m_type(eGT_Normal),
m_have_rect(false)
{ 
}

Group::~Group(void)
throw()
{
        if (!m_map || eGT_Path != m_type)
                return;

        this->nukePath();
}



////////////////////////////////////////////////////////////////////////////////
//
//      Group class methods
//
////////////////////////////////////////////////////////////////////////////////

void
Group::addMeta
(
IN const char * key,
IN const char * value
)
{
        ASSERT(key, "null key passed to addMeta()");
        ASSERT(value, "null value passed to addMeta()");

        ASSERT(key[0], "empty key passed to addMeta()");
        // ASSERT(value[0]) -- this is okay
        m_meta[key] = value;

        // interception--is this a path?
        if (!strcmp("vgfxPath", key)) {
                m_type = eGT_Path;
                this->nukePath();
                this->expandPath(value);
        }
}



void
Group::addObject
(
IN const object_t& obj
)
{
        const char * tag = obj.getTag();
        ASSERT(*tag, "null tag?");

        if (!objtree::isValidPropertyName(tag)) {
                WAVE_EX(wex);
                wex << "Invalid object tag: '" << tag << "'";
        }

        map_obj_t::iterator i = this->findObject(tag);
        if (m_objects.end() != i) {
                WAVE_EX(wex);
                wex << "Multiple group objects with the same tag: '" << tag;
                wex << "'";
        }

        m_objects.insert(map_obj_t::value_type(obj.z, obj));
}



static void
writeXY
(
IO std::ostream& stream,
IN float x,
IN float y
)
{
        long x_l = (long)(1000.0 * x + 0.5);
        long y_l = (long)(1000.0 * y + 0.5);

        stream << "x" << x_l << "y" << y_l;
}


#define PERSIST_VAL2(q,v) { if (obj.q) { stream << "\t" << #q << " " << (v); } }
#define PERSIST_VAL(q) PERSIST_VAL2(q, obj.q)

void
Group::persist
(
IO std::ostream& stream
)
const
{
        perf::Timer timer("Group::persist");

        stream << "group {\n";
        stream << "\tid\t" << this->getID() << "\n";

        for (Dictionary::const_iterator i = m_meta.begin(); i != m_meta.end();
             ++i) {
                const char * name = i->first.c_str();
                const char * value = i->second.c_str();

                // HACK for paths.  TODO: clean this up
                if (!strcmp("vgfxPath", name)) {
                        continue;       // skip this (see below)
                }

                stream << "\tmeta\t" << name << " \"" << value << "\"\n";
        }

        // TODO: clean up the concept of path==group!
        //      checking for "vgfxPath" everywhere is bogus
        if (eGT_Path == m_type) {
                // OUCH.  we have to reconstruct our vgfxPath meta value,
                // since user erasures or other actions may have deleted
                // some arbitrary number of child objects.  Even worse, we
                // have to reconstruct ordering based on IDs.

                // TODO: this is so hideous it is beyond words.  But it's
                // late and I haven't had any better ideas.  I suspect there
                // needs to be another layer here but I'll think about it
                // later.

                // first: get an ordered list of child objects
                SetString ordered;
                for (map_obj_t::const_iterator i = m_objects.begin();
                     i != m_objects.end(); ++i) {
                        ordered.insert(i->second.ref.getID());
                }

                // next: walk ordered list, write paths
                VecString null_path;    // empty
                dictionary_t data;
                float x0 = 0.0;         // previous control point
                float y0 = 0.0;
                stream << "\tmeta\tvgfxPath \"";
                for (SetString::iterator i = ordered.begin();
                     i != ordered.end(); ++i) {
                        const char * id = i->c_str();

                        Primitive * p = m_map->findObject(id);
                        ASSERT(p, "bezier object not there '%s'", id);
                        p->getContainerDictionary(null_path, data);

                        float x = atof(getRequiredValue(data, "x0"));
                        float y = atof(getRequiredValue(data, "y0"));

                        // need to write old values?
                        if (x != x0 || y != y0) {
                                writeXY(stream, x0, y0);
                                stream << "|g0|";
                        }
                        writeXY(stream, x, y);
                        stream << "|";

                        x0 = atof(getRequiredValue(data, "x2"));
                        y0 = atof(getRequiredValue(data, "y2"));
                }

                // write closing point
                writeXY(stream, x0, y0);
                stream << "\"\n}";
                return; // short-circuit
        }

        // happy case: this isn't a path and we can just persist child records
        for (map_obj_t::const_iterator i = m_objects.begin();
             i != m_objects.end(); ++i) {
                const object_t& obj = i->second;
                const char * tag = obj.getTag();

                stream << "\tobject\ttag " << tag;
                stream << "\tid " << obj.ref.getID();
                PERSIST_VAL(x)
                PERSIST_VAL(y)
                PERSIST_VAL(z)
                if (1 != obj.scale) {
                        PERSIST_VAL(scale)
                }
                PERSIST_VAL2(phi, 180.0 * obj.phi / M_PI);
                stream << "\n";
        }

        stream << "}";
}



void
Group::listContainers
(
IN const VecString& path,
OUT VecString& ids
)
const
{
        ids.clear();
        if (path[0] == "meta") {
                for (Dictionary::const_iterator i = m_meta.begin();
                     i != m_meta.end(); ++i) {
                        ids.push_back(i->first);
                }
        } else if (path[0] == "object") {
                for (map_obj_t::const_iterator i = m_objects.begin();
                     i != m_objects.end(); ++i) {
                        ids.push_back(i->second.tag);
                }
        } else {
                WAVE_EX(wex);
                wex << "Unknown path for group: " << path[0];
        }
}



bool
Group::doesContainerExist
(
IN const VecString& path
)
const
{
        if (path[0] == "meta") {
                return (m_meta.end() != m_meta.find(path[1]));
        } else if (path[0] == "object") {
                return (m_objects.end() != this->findObject(path[1].c_str()));
        }
        return false;
}


bool
Group::canCreateContainer
(
IN const VecString& path
)
const
{
        if (path[0] == "meta" || path[0] == "object")
                return true;
        return false;
}


void
Group::removeContainer
(
IN const VecString& path
)
{
        if (path.size() > 2) {
                WAVE_EX(wex);
                wex << "Path is too large for group (" << path.size();
                wex << " elements)";
        }

        if (path[0] == "meta") {
                Dictionary::iterator i = m_meta.find(path[1]);
                if (m_meta.end() == i) {
                        WAVE_EX(wex);
                        wex << "Cannot remove this meta data element '";
                        wex << path[1] << "' since it does not exist.";
                }
                m_meta.erase(i);
        } else if (path[0] == "object") {
                map_obj_t::iterator i = this->findObject(path[1].c_str());
                if (m_objects.end() == i) {
                        WAVE_EX(wex);
                        wex << "Cannot remove this object '" << path[1];
                        wex << "' since it does not exist.";
                }
                m_objects.erase(i);
        } else {
                WAVE_EX(wex);
                wex << "Unknown path in group: '" << path[0] << "'";
        }
}


void
Group::getContainerDictionary
(
IN const VecString& path,
OUT dictionary_t& data
)
const
{
        //perf::Timer timer("Group::getContainerDictionary");

        if (path.size() > 2) {
                WAVE_EX(wex);
                wex << "path is too large for group (" << path.size();
                wex << " elements)";
        }

        data.clear();
        if (path[0] == "meta") {
                const char * name = path[1].c_str();
                Dictionary::const_iterator i = m_meta.find(name);
                if (m_meta.end() == i) {
                        WAVE_EX(wex);
                        wex << "No meta data field with name '" << name;
                        wex << "' exists in this group";
                }
                const char * value = i->second.c_str();
                data[name] = value;
        } else if (path[0] == "object") {
                map_obj_t::const_iterator i = this->findObject(path[1].c_str());
                if (m_objects.end() == i) {
                        WAVE_EX(wex);
                        wex << "No object with tag '" << path[1] << "' exists";
                        wex << " in this group";
                }
                const object_t& obj = i->second;
                const char * tag = obj.getTag();
                data["tag"] = tag;
                data["id"] = obj.ref.getID();
                data["x"] = getStringValue(obj.x);
                data["y"] = getStringValue(obj.y);
                data["z"] = getStringValue(obj.z);
                data["scale"] = getStringValue(obj.scale);
                data["phi"] = getStringValue(180 * obj.phi / M_PI);
        } else {
                WAVE_EX(wex);
                wex << "Invalid path for dictionary retrieval: '" << path[0];
                wex << "'";
        }
}



void
Group::setContainerDictionary
(
IN const VecString& path,
IN const dictionary_t& data
)
{
//      perf::Timer timer("Group::setContainerDictionary");

        if (path.size() > 2) {
                WAVE_EX(wex);
                wex << "Path is too long for group (" << path.size();
                wex << " elements)";
        }

        if (path[0] == "meta") {
                const char * name = path[1].c_str();
                const char * value = getRequiredValue(data, name);
                this->addMeta(name, value);
        } else if (path[0] == "object") {
                map_obj_t::iterator i = this->findObject(path[1].c_str());
                if (m_objects.end() == i) {
                        // need to create!
                        object_t obj;
                        const char * in_tag = path[1].c_str();
                        const char * tag = getOptionalValue(data, "tag", in_tag);
                        if (strcmp(tag, in_tag)) {
                                WAVE_EX(wex);
                                wex << "tag for new object '" << tag << "' ";
                                wex << "does not match path '" << path[1];
                                wex << "'";
                        }
                        const char * id = getValue(data, "id");
                        ASSERT_THROW(id, "Cannot setContainerDictionary(): " <<
                            "need to create new object, and no 'id' field " <<
                            "exists on input");
                        obj.ref.setID(m_map, id);
                        obj.tag = tag;
                        obj.x = atof(getOptionalValue(data, "x", "0.0"));
                        obj.y = atof(getOptionalValue(data, "y", "0.0"));
                        obj.z = atof(getOptionalValue(data, "z", "0.0"));
                        obj.scale = atof(getOptionalValue(data, "scale", "1.0"));
                        obj.phi = atof(getOptionalValue(data, "phi", "0.0"));
                        obj.phi *= M_PI / 180.0;
                        updateObjectTransform(obj);
                        this->addObject(obj);
                } else {
                        // update existing
                        object_t& obj = i->second;
                        for (dictionary_t::const_iterator j = data.begin();
                             j != data.end(); ++j) {
                                const char * name = j->first.c_str();
                                const char * value = j->second.c_str();

                                if (!strcmp("id", name)) {
                                        obj.ref.setID(m_map, value);
                                } else if (!strcmp("x", name)) {
                                        obj.x = atof(value);
                                } else if (!strcmp("y", name)) {
                                        obj.y = atof(value);
                                } else if (!strcmp("z", name)) {
                                        obj.z = atof(value);
                                } else if (!strcmp("scale", name)) {
                                        obj.scale = atof(value);
                                } else if (!strcmp("phi", name)) {
                                        obj.phi = M_PI * atof(value) / 180.0;
                                } else if (!strcmp("tag", name)) {
                                        if (path[1] != value) {
                                                WAVE_EX(wex);
                                                wex << "Cannot change tag ";
                                                wex << "value from '" << path[1];
                                                wex << "' to '" << value << "'";
                                        }
                                } else {
                                        WAVE_EX(wex);
                                        wex << "Cannot set this field for a ";
                                        wex << "group object element: '";
                                        wex << name << "'";
                                }
                        }
                        updateObjectTransform(obj);
                }
        } else {
                WAVE_EX(wex);
                wex << "Invalid path in group: '" << path[0] << "'";
        }
}



void
Group::recalcBoundingRect
(
IN const char * tag_path,
IN Drawer * drawer,
IN const xform_2d_t& T
)
throw()
{
        ASSERT(tag_path, "null tag path");
        ASSERT(drawer, "null drawer");
        ASSERT(m_map, "null object map");

//      DPRINTF("In Group::getBoundingRect(%s)", this->getID());

        static const int s_tokSize = 256;
        char element[s_tokSize];
        int offset = getPathElement(tag_path, element, s_tokSize);
        ASSERT(offset >= 0, "Failed to get next path element: '%s'", tag_path);
        const char * next_path = tag_path + offset;
//      DPRINTF("Path is '%s',  element is '%s', remainder is '%s'",
//           tag_path, element, next_path); 

        bool isWildcard = !strcmp("*", element);

        // update brush
        PushPopBrush ppb(drawer, getDwordFromPointer(this));
        this->updateDrawer(drawer, T);

        // T.dump("input transformation");

        // our bounding rect is the sum of all interior rects
        m_have_rect = false;            // need to compute at least one child
        rect_t r;
        r.left = r.top = r.right = r.bottom = 0.0;      // default

        // loop through objects
        for (map_obj_t::const_iterator i = m_objects.begin();
            i != m_objects.end(); ++i) {
                const object_t& obj = i->second;

                // get this object
                Primitive * p = m_map->findObject(obj.ref.getID());
                ASSERT(p, "all required sub objects should exist");

                // only recurse if we think this child needs it
                if (isWildcard || !strcmp(element, obj.getTag())) {
                        // construct child's transformation
                        xform_2d_t subT;        // local --> absolute
                        subT.setToProductOf(T, obj.xform);

                        // obj.xform.dump("parent->child transform");
                        // subT.dump("Total child->global transform");

                        // recalculate bounding rects for this child tree
                        //    (recursive call--don't wrap in a timer)
                        p->recalcBoundingRect(next_path, drawer, subT);
                }

                // another scope for clean timing
                {
                        // only enable for debugging!
                        // perf::Timer timer("Group::recalc-child-xform2");

                        // get bounding rect in object's local coordinates
                        rect_t child;
                        if (!p->getBoundingRect(child)) {
                                // child doesn't have a bounding rect--skip it
                                continue;
                        }

                        // child.dump("Child's bounding rect");
                        rect_t xc;      // xc - transformed child rectangle
                        obj.xform.transformRect(child, xc);
                        // xc.dump("Transformed child rect");

                        if (!m_have_rect) {
                                r = xc;
                                m_have_rect = true;
                        } else {
                                r.inflate(xc);
                        }
                        // r.dump("  Resulting rect");
                }
        }

        // have a clip rect?  Then it's easy
        const char * w = getValue(m_meta, "vgfxClipWidth");
        const char * h = getValue(m_meta, "vgfxClipHeight");
        if (w && h) {
                r.left = r.top = 0.0;
                r.right = atof(w);
                r.bottom = atof(h);
                m_have_rect = true;
        }

        m_bounding = r;
//      r.dump(this->getID());
        // DPRINTF("  ...exiting Group::getBoundingRect(%s)", this->getID());
}



bool
Group::getBoundingRect
(
OUT rect_t& r
)
const throw()
{
        r = m_bounding;
        return m_have_rect;
}



bool
Group::getPrimitive
(
IN const char * tag_path,
IN const xform_2d_t& T,
OUT visit_result_t& vr
)
{
        ASSERT(tag_path, "null tag path");

        // DPRINTF("Looking for object at path: '%s'", tag_path);

        static const int s_tokSize = 256;
        char element[s_tokSize];
        int offset = getPathElement(tag_path, element, s_tokSize);
        ASSERT(-1 != offset, "path element is too large");

        // special case
        if (!*element) {
                // DPRINTF("This must be the root!");
                vr.tag_path = tag_path;
                vr.T = T;
                vr.p = this;
                return true;
        }

        map_obj_t::iterator i = this->findObject(element);
        if (m_objects.end() == i) {
                // DPRINTF("No object with tag '%s'", element);
                vr.clear();
                return false;
        }

        object_t& obj = i->second;

        // update transformation
        xform_2d_t newT;
        newT.setToProductOf(T, obj.xform);

        // look up this child
        vgfx::Primitive * p = m_map->findObject(obj.ref.getID());
        ASSERT(p, "tag found but no primitive");

        // is this the primitive we want, or just a parent?
        if (*(tag_path + offset)) {
                // there is more to the path
                return p->getPrimitive(tag_path + offset, newT, vr);
        }

        // just return this child directly
        vr.tag_path = tag_path;
        vr.T = newT;
        vr.p = p;
        return true;
}



void
Group::draw
(
IN Drawer * drawer,
IN const rect_t& r_cm,  // draw rect in absolute coordinates (cm)
IN const xform_2d_t& T  // local --> absolute (cm)
)
{
        ASSERT(drawer, "null drawer");

        /*
        DPRINTF("Group::draw(%s)", this->getID());
        r_cm.dump("draw rect");
        T.dump("transform");
        */

        // if this is a printer, see if we should print at all
        if (drawer->isPrinter()) {
                const char * val = getValue(m_meta, "vgfxPrintable");
                if (val && !strcmp(val, "false")) {
                        DPRINTF("'%s' has requested not to print",
                            this->getID());
                        return;
                }
        }

        // update brush
        PushPopBrush ppb(drawer, getDwordFromPointer(this));
        this->updateDrawer(drawer, T);

        // walk through all children, draw
        for (map_obj_t::const_iterator i = m_objects.begin();
            i != m_objects.end(); ++i) {
                const object_t& obj = i->second;

                // put in separate scope so we get a clean timer (does not
                //  include recursion to children)
                Primitive * p = NULL;
                xform_2d_t subT;        // child coords --> absolute (CM)
                {
                        // actually, this is fast enough that the timer itself
                        //   impacts performance!
                        // only enable timer for debugging
                        // perf::Timer timer("Group::draw-child-xform");

                        // get this object
                        p = m_map->findObject(obj.ref.getID());
                        ASSERT(p, "all required sub objects should exist");

                        // construct child's transformation
                        subT.setToProductOf(T, obj.xform);
                        // obj.xform.dump("child transform");

                        // get bounding rect in object's local coordinates
                        rect_t child;
                        if (!p->getBoundingRect(child)) {
                                // child doesn't have a bounding rect--skip it
                                continue;
                        }

                        // transform to global -- hit?
                        rect_t globalR;
                        subT.transformRect(child, globalR);

                        // child.dump("child in local coords");
                        // globalR.dump("child in global coords");

                        // intersects at all?
                        if (!r_cm.intersects(globalR))
                                continue;       // nope, doesn't intersect
                }

                // allow child tree to draw
                p->draw(drawer, r_cm, subT);
        }

        // supposed to draw bounding rect?  do so last
        const char * draw_bounds = getValue(m_meta, "vgfxDrawBounds");
        if (draw_bounds && !strcmp("true", draw_bounds)) {
                drawer->setTransform(T);
                drawer->fillRect(m_bounding);
        }

        // close out any paths
        drawer->endPath(); 
}



bool
Group::visit
(
IN const rect_t& r,             // global coordinates (cm)
IN const xform_2d_t& T,         // local --> global transformation
IN const char * tag_path,
IN callback_t callback,
IN void * context,
IN eHitDetect hit
)
{
        // perf::Timer timer("Group::visit"); -- too high level
        ASSERT(callback, "Group::visit() called with null callback");
        ASSERT(tag_path, "null tag path?");

        // A note about hit-detection logic.
        //  If hit = eHit_Always, we don't make any checks, and always recurse
        //  If hit = eHit_Intersects, we will recurse on any intersection
        //  If hit = eHit_Contains, we'll recurse on any intersection (yes!)
        //     when hit = eHit_Contains, we'll callback only if we are contained
        //     We have to recurse on simple intersections in case a contained
        //     object is fully contained by the input rect.

        // call with ourselves (maybe)
        bool notify = true;
        if (eHit_Contained == hit) {
                rect_t me;
                this->getBoundingRect(me);
                rect_t xme;             // transformed me
                T.transformRect(me, xme);
                notify = r.contains(xme);
        }

        if (notify) {
                visit_result_t vr;
                vr.p = this;
                vr.tag_path = tag_path;
                vr.T = T;
                if (!callback(context, vr))
                        return false;   // client asked to stop iterating
        }

        // recurse into children
        for (map_obj_t::const_iterator i = m_objects.begin();
             i != m_objects.end(); ++i) {
                const object_t& obj = i->second;

                // separate scope for clean timing
                bool recurse = true;
                xform_2d_t childT;
                Primitive * p = NULL;
                {
                        perf::Timer timer("Group::visit--child xform");

                        // find object
                        p = m_map->findObject(obj.ref.getID());
                        ASSERT(p, "all subobjects should exist");
        //              DPRINTF("testing child '%s'", p->getID());

                        // get transform from this child --> global
                        childT.setToProductOf(T, obj.xform);

                        if (eHit_Always != hit) {
                                // get child's bounding rect
                                rect_t childR;
                                p->getBoundingRect(childR);

                                // child rect in global coordinates
                                rect_t globalR; 
                                childT.transformRect(childR, globalR);

                                // r.dump("draw rect");
                                // globalR.dump("child rect");
                                recurse = r.intersects(globalR);
                        }
                }

                if (recurse) {
                        ASSERT(p, "null node for recursion?");
                        // intersects, so recurse
                        std::string new_path = tag_path;
                        new_path += "/";
                        new_path += obj.getTag();
                        if (!p->visit(r, childT, new_path.c_str(), callback,
                             context, hit)) {
                                return false;   // client wanted to stop
                        }
                }
        }

        // success
        return true;
}


map_obj_t::iterator
Group::findObject
(
IN const char * tag
)
throw()
{
        ASSERT(tag, "null");

        for (map_obj_t::iterator i = m_objects.begin(); i != m_objects.end();
             ++i) {
                object_t& obj = i->second;
                if (obj.tag == tag) {
                        return i;
                }
        }

        return m_objects.end();
}



map_obj_t::const_iterator
Group::findObject
(
IN const char * tag
)
const throw()
{
        ASSERT(tag, "null");

        for (map_obj_t::const_iterator i = m_objects.begin();
             i != m_objects.end(); ++i) {
                const object_t& obj = i->second;
                if (obj.tag == tag) {
                        return i;
                }
        }

        return m_objects.end();
}



void
Group::updateDrawer
(
IN Drawer * drawer,
IN const xform_2d_t& T          // local --> global
)
{
//      perf::Timer timer("Group::updateDrawer");

        ASSERT(drawer, "null");

        // set transformation
        drawer->setTransform(T);

        // update brush based on group meta values
        updateBrush(m_meta, drawer);

        // clip rect?
        const char * w = getValue(m_meta, "vgfxClipWidth");
        const char * h = getValue(m_meta, "vgfxClipHeight");
        if (w && h) {
                drawer->setClipRect(0.0, 0.0, atof(w), atof(h));
        }
}



void
Group::expandPath
(
IN const char * path
)
{
        ASSERT(path, "null");

//      DPRINTF("expanding path = '%s'", path);

        // first, construct vector of points
        typedef std::vector<point_t> vec_pt_t;
        vec_pt_t strokes;
        const char * p = path;
        point_t pt;     // current point
        bool is_gap = false;
        int id_ctr = 0;
        while (*p) {
                // determine token
                char a = *p;
                ++p;

                // get value
                long l = atol(p);
                float f = 0.001 * l;    // convert to CM

                // walk forward to next token
                if ('-' == *p) { ++p; }
                while (*p && isdigit(*p)) { ++p; }

                // update point if necessary
                if ('x' == a)
                        pt.x = f;
                if ('y' == a)
                        pt.y = f;
                if ('g' == a)
                        is_gap = true;

                // keep parsing event?
                if (*p && '|' != *p)
                        continue;

                // just add point?
                if (!is_gap) {
        //              DPRINTF("  (%5.2f, %5.2f)", pt.x, pt.y);
                        strokes.push_back(pt);
                }

                if (!is_gap && *p)
                        continue;

                // gap or end -- add strokes as bezier path!
                // ignore short paths
                if (strokes.size() < 2) {
                        continue;
                }

                // now, convert to beziers
                float ds = 1.0;         // WTF?
                bezier::quad_path_t b_path;
                bezier::getQuadPathFromRawPoints(&strokes[0], strokes.size(),
                    ds, b_path);

                // add beziers as child objects
                for (bezier::quad_path_t::iterator i = b_path.begin();
                     i != b_path.end(); ++i) {
                        const bezier::quad_bezier_t& qb = *i;
        
                        // create bezier object
                        init_quad_t iq;
                        iq.id = this->getID();
                        iq.id += "K";
                        iq.id += getStringValue(id_ctr);
                        ++id_ctr;
                        iq.quad = qb;
                        smart_ptr<Primitive> quad = create_quad(iq);
                        ASSERT(quad, "failed to create new quad bezier");

                        // add to map
                        m_map->addObject(quad);

                        // construct object record
                        object_t obj;
                        obj.clear();
                        obj.ref.setID(m_map, iq.id.c_str());
                        obj.tag = iq.id;
                        this->addObject(obj);
                }
                strokes.clear();
                is_gap = false;
        }
}



void
Group::nukePath
(
void
)
{
        ASSERT(eGT_Path == m_type, "only valid for path objects!");

        // this is a path--nuke all children from map!
        VecString ids;
        for (map_obj_t::iterator i = m_objects.begin(); i != m_objects.end();
             ++i) {
                const char * id = i->second.ref.getID();
                ids.push_back(id);
        }
        m_objects.clear();
        for (VecString::iterator i = ids.begin(); i != ids.end(); ++i) {
                const char * id = i->c_str();
                // DPRINTF("Removing from map: '%s'", id);
                m_map->removeObject(id);
        }
}



////////////////////////////////////////////////////////////////////////////////
//
//      static helper methods
//
////////////////////////////////////////////////////////////////////////////////

static void
constructObject
(
IN ObjectMap * map,
IN const dictionary_t& data,
OUT object_t& obj
)
{
        ASSERT(map, "null");

        obj.tag = getRequiredValue(data, "tag");
        obj.ref.setID(map, getRequiredValue(data, "id"));
        obj.x = atof(getOptionalValue(data, "x", "0.0"));
        obj.y = atof(getOptionalValue(data, "y", "0.0"));
        obj.z = atof(getOptionalValue(data, "z", "0.0"));
        obj.scale = atof(getOptionalValue(data, "scale", "1.0"));

        obj.phi = atof(getOptionalValue(data, "phi", "0.0"));
        obj.phi = M_PI * obj.phi / 180.0;       // degrees --> radians

        updateObjectTransform(obj);
}



smart_ptr<Primitive>
parseGroup
(
IN std::istream& stream,
IO ObjectMap * map
)
{
        perf::Timer timer("parseGroup");

        ASSERT(map, "null object map passed to parseGroup()");

        smart_ptr<Group> group = new Group(map);
        ASSERT(group, "out of memory");

        std::string line, token, value;

        // keep reading lines
        while (true) {
                line = getNextLineFromStream(stream, s_line_behavior);
                const char * cursor =
                    getNextTokenFromString(line.c_str(), token, eParse_None);

                // empty?
                if ("" == token) {
                        continue;       // empty line
                }

                if ("id" == token) {
                        getNextTokenFromString(cursor, value, eParse_RespectQuotes);
                        group->setID(value.c_str());
                } else if ("meta" == token) {
                        std::string name;
                        cursor = getNextTokenFromString(cursor, name, eParse_None);
                        cursor = getNextTokenFromString(cursor, value, eParse_RespectQuotes);

                        group->addMeta(name.c_str(), value.c_str());
                } else if ("object" == token) {
                        dictionary_t dict;
                        getDictionaryFromString(cursor, "object", dict);

                        object_t obj;
                        constructObject(map, dict, obj);
                        // DPRINTF("  Adding object with tag='%s', id='%s'",
                        //    tag.c_str(), obj.ref.getID());
                        // obj.xform.dump("object transform");
                        group->addObject(obj);
                } else if ("}" == token) {
                        break;          // end of group!
                } else {
                        WAVE_EX(wex);
                        wex << "Unknown line keyword in group: '" << token;
                        wex << "'";
                }
        }

        return group;
}


};      // vgfx namespace