AGG 文档翻译 - 基础渲染器

基础渲染器

Agg有2个基础渲染器，这2个渲染器有着几乎相同的函数，它们是：renderer_base 和 renderer_mclip。第一个是最常用的，它在底层次上实现裁剪。一般说来裁剪是一项复杂的工作，agg中至少有2个层次的裁剪，低层次(像素)裁剪和高层次（向量）裁剪。这些渲染器类在像素层实施裁剪是为了保护buffer内存访问不越界。Renderer_mclip类可以实施多矩形区域裁剪，但是它的性能受矩形个数的影响。

Renderer_base和renderer_mclip是以像素类型渲染器作为参数的类模板：

template<class PixelFormat> class renderer_base

{

public:

    typedef PixelFormat pixfmt_type;

    typedef typename pixfmt_type::color_type color_type;

    . . .

};

请参考renderer_base和renderer_mclip的源代码。

 

创建

renderer_base(pixfmt_type& ren);

renderer_mclip(pixfmt_type& ren);

两个类都接受一个像素格式渲染器的引用，rederer_mclip使用renderer_base<PixelFormat>在其内部来实现单矩形区域的裁剪，请注意你可以使用pixel_amask_adapter来作为PixelFormatd 的模板参数。

创建基础渲染器的代价是非常小的，它只是初始化了类成员变量。但是renderer_mclip会在增加裁剪矩形的时候分配内存，并在对象销毁的时候释放内存。它使用pod_deque类来分配相同大小的内存块，并且再也不会为它重新分配内存。当你重置（清空）了裁剪区域，已经分配的内存不会被回收，而会被重用，renderer_mclip只会在对象销毁的时候才会释放内存。这个技术在agg中被广泛使用，用来防止深度的内存碎片。

 

成员函数：

const pixfmt_type& ren() const;

pixfmt_type& ren();

返回像素类型渲染器的引用；

unsigned width()  const;

unsigned height() const;

返回渲染buffer的宽高；

void reset_clipping(bool visibility);

这个函数重置裁剪，如果visibility为true那么裁剪区被设置成(0,0,width()-1, height()-1),如果为false，那么裁剪区被设置成一个不可见的区域，如(1,1,0,0)。在renderer_mclip中此函数同样也删除所有之前添加的裁剪区。

重要提示：

如果你为渲染buffer绑定了另一个内存buffer，并与这个特殊的基础渲染器相关联，那么你必须要调用reset_clipping，否则裁剪区将会非法，因为此时基础渲染器没有从渲染buffer中得到任何“反馈”，换句话说，renderer_base和renderer_mclip不知道渲染buffer的任何改变，在这个例子中使用事件机制或者代理又显得多余。

bool clip_box(int x1, int y1, int x2, int y2);

 

设置新的裁剪区，仅renderer_base有这个函数，裁剪区包含边界信息，所以它的最大值是(0,0,width()-1, height()-1)。裁剪区在被设置前默认为此最大值，所以设置裁剪区的值超过这个最大值是安全的。

 

void add_clip_box(int x1, int y1, int x2, int y2);

增加一个新的裁剪区，仅renderer_mclip类有此函数，你可以添加任意数量的矩形裁剪区，但是它们不能重叠，如果其中有重叠的区域，那么某些元素可能被绘制2次或者以上，在添加裁剪区之前，考虑性能的因素，裁剪区默认为(0, 0, width()-1, heigth()-1)。这也意味着调用renderer_mclip的reset_clipping(false)函数是没有道理的（不应该的），因为调用这个函数后renderer_mclip所有添加的裁剪区将会被一个不可见的区域裁剪(renderer_base中的裁剪区已经被置成1，1，0，0），并且不会被真正的添加。可见区域也包括了裁剪区域的边界，也就是说add_clip_box(100, 100, 100, 100)将添加一个只有一个像素的裁剪区。

 

void clip_box_naked(int x1, int y1, int x2, int y2);

仅renderer_base有此函数，设置新的裁剪区但是此区域并不与之前添加的裁剪区发生裁剪运算（清除了旧的裁剪区，设置一个新的裁剪区）。这个函数是不安全的，一般在renderer_mclip中被调用，目的是为了在渲染时在不同区域间切换和避免额外的开销。

 

bool inbox(int x, int y) const;

检查点(x, y)是否在裁剪区中，仅renderer_base有此函数。

 

void first_clip_box();

bool next_clip_box();

这2个函数用来枚举出渲染器中的所有裁剪区，在renderer_base中他们是空的，next_clip_box()永远返回false。

 

const rect& clip_box() const;

int         xmin()     const;

int         ymin()     const;

int         xmax()     const;

int         ymax()     const;

以一个矩形或者以单个整数的方式返回裁剪区，在renderer_mclip中这些函数恒返回(0, 0, width()-1, height()-1)（因为返回的是renderer_base中的裁剪区，而这个裁剪区没有被修改过）。