vase_renderer_draft1_2

Vase Renderer

first draft, version 0.25 (VaseR draft1_2)

About

Vase renderer(VaseR) is a 2D graphics renderer built on top of OpenGL. Unlike most graphics libraries which are based on SetPixel(), VaseR is based on glDrawArrays(). That means, VaseR takes the advantage of GPU rasterization. Another unique feature of VaseR is rendering with premium quality anti- aliasing using 'fade polygons', as mentioned in this article.

Getting started

To properly use VaseR, you need to understand what role does VaseR play in the rendering pipeline. Suppose your application has a 2D rendering pipeline like:

model transformation

clippings

view transformation

primitives generation i.e. glDrawArrays(); and/or glBegin(); glEnd();

OpenGL pipeline...

VaseR is a renderer and merely takes care the primitives generation part (highlighted in red). You should set the gl states to meet VaseR's requirements before calling any VaseR function:

blending	glEnable(GL_BLEND); glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
vertex array client states	glEnableClientState(GL_VERTEX_ARRAY); glEnableClientState(GL_COLOR_ARRAY); glDisableClientState(GL_EDGE_FLAG_ARRAY); glDisableClientState(GL_FOG_COORD_ARRAY); glDisableClientState(GL_INDEX_ARRAY); glDisableClientState(GL_NORMAL_ARRAY); glDisableClientState(GL_SECONDARY_COLOR_ARRAY); glDisableClientState(GL_TEXTURE_COORD_ARRAY);
other	gl's default important: no back face culling

Beginners' tips: hide
How to correctly set gl states for VaseR..

Suppose you have a helloworld application that only renders a line segment in draw():

void draw()
{
 glMatrixMode(GL_PROJECTION);
 glPushMatrix();
  glLoadIdentity();
  glOrtho( 0,context_width,context_height,0,0.0f,100.0f);
  glLineWidth(2.0);
  glBegin(GL_LINES);
   glColor4f(1,0,0.5, 1);
   glVertex2f(10,100);
   glColor4f(0.5,0,1, 1);
   glVertex2f(100,300);
  glEnd();
  //other drawings
 glMatrixMode(GL_PROJECTION);
 glPopMatrix();
}

extend it into:

void draw()
{
 glMatrixMode(GL_PROJECTION);
 glPushMatrix();
 
  glEnable(GL_BLEND);
  glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
   glLoadIdentity();
   glOrtho( 0,context_width,context_height,0,0.0f,100.0f);

   glEnableClientState(GL_VERTEX_ARRAY);
   glEnableClientState(GL_COLOR_ARRAY);
    { Vec2  P1 = {10,100};
     Vec2  P2 = {100,300};
     Color C1 = {1,0,0.5, 1};
     Color C2 = {0.5,0,1, 1};
     double W1= 2.0;
     double W2= W1;
     
     segment(P1,P2, C1,C2, W1,W2, 0);
    }
    //other VaseR calls
   glDisableClientState(GL_VERTEX_ARRAY);
   glDisableClientState(GL_COLOR_ARRAY);

   //other drawings with blending
  glDisable(GL_BLEND); //restore blending options
  
  //other drawings without blending
 glMatrixMode(GL_PROJECTION);
 glPopMatrix();
}

Usage

Provide these structs to VaseR before any vase_renderer_* include by:

struct Vec2 { double x,y;};
struct Color { float r,g,b,a;};
or
typedef your_vec2 Vec2;
typedef your_color Color;

#include "../include/vase_renderer_draft1_2.cpp"

The recommended way is to include "vase_renderer_draft1_2.cpp" .

You should not include "vector_operations.h" or "vertex_array_holder.h" directly. It may break things. They are included by "vase_renderer_draft1_2.cpp".

To compile "vase_renderer_draft1_2.cpp" separately, create an empty cpp file to provide the structs:

//file vase_renderer.cpp
 struct Vec2 { double x,y;};
 struct Color { float r,g,b,a;};
 #include "vase_renderer_draft1_2.cpp"
//end of file

Documentation

API design

VaseR has no states, only a set of functions. Thus you need to pass many parameters to a VaseR function on each call. And these parameters are stored in structures like WinAPI does. Normally if you do not know what options to set, just put 0 at the parameter polyline_opt*. VaseR ensures empty parameter polyline_opt* options=0 and empty structure polyline_opt opt={0}; are default options and would not cause any error.

polyline() For technical details about polyline() look at here. void polyline( Vec2* P, //array of point of a polyline Color* C, //array of color double* weight,//array of weight int size_of_P, //size of the buffers polyline_opt* options); //extra options All arrays must be of the same size otherwise memory error will occur. options struct polyline_opt { //set the whole structure to 0 will give default options char joint; #define LJ_miter 0 #define LJ_bevel 1 #define LJ_round 2 char cap; #define LC_butt 0 #define LC_round 1 #define LC_square 2 #define LC_rect 3 //unique to vase renderer bool feather; double feathering; bool no_feather_at_cap; bool no_feather_at_core; }; polyline_opt opt={0}; //consider this structure: opt.joint LJ_miter LJ_bevel LJ_round opt.cap LC_butt LC_round LC_square LC_rect LC_rect is related to feathering. Unlike the above 3 common cap types, LC_rect is unique to VaseR. LC_rect puts the fade polygon out of the end points of a polyline. When feather=false, LC_rect looks very close to LC_butt. The difference is only obvious at high value of feathering. LC_rect (with high value of feathering) LC_butt (with high value of feathering) opt.feather, opt.feathering, opt.no_feather_at_cap, opt.no_feather_at_core feathering is a multiplier to the magnitude of the fade polygon. do not set it to lower than 1.0 . feathering is unique to VaseR. A feathered polyline with round cap and round joint can mimic the feel of an air brush stroke. opt.feather = false; opt.feather = true; opt.feathering = 8.0; opt.feather = true; opt.feathering = 8.0; opt.no_feather_at_cap = true; opt.no_feather_at_core = false; opt.feather = true; opt.feathering = 8.0; opt.no_feather_at_cap = false; opt.no_feather_at_core = true; remarks: no_feather_at_cap only affects cap type LC_butt, LC_square and LC_rect . Usage void sample_polyline() { int size_of_AP=4; Vec2 AP[size_of_AP]; AP[0].x=200; AP[0].y=50; AP[1].x=100; AP[1].y=150; AP[2].x=300; AP[2].y=150; AP[3].x=200; AP[3].y=250; Color AC[size_of_AP]; { Color col={1 , 0, 0, 1}; cc[0]=col;} { Color col={.8,.8, 0, 1}; cc[1]=col;} { Color col={ 0, 0, 1, 1}; cc[2]=col;} { Color col={1 , 0, 0, 1}; cc[3]=col;} double Aw[size_of_AP]; Aw[0] = 8.0; Aw[1] = 8.0; Aw[2] = 8.0; Aw[3] = 8.0; polyline_opt opt={0}; polyline( AP, AC, Aw, size_of_AP, &opt); } example program is at samples/polyline under VaseR package. Notes Varying color is stable but will cause overdraw at degenerated cases. Varying weight is unstable. polyline() will "go wild" when a segment is shorter than its own width. Further work After solving the above 3 mentioned problems, can provide the choice between color blending profiles, possibly 'hard' and 'soft'.

segment() void segment( const Vec2& P1, const Vec2& P2, //coordinates const Color& C1, const Color& C2, //colors double W1, double W2, //weights const polyline_opt* options) //extra options { Vec2 AP[2]; Color AC[2]; double AW[2]; AP[0] = P1; AC[0] = C1; AW[0] = W1; AP[1] = P2; AC[1] = C2; AW[1] = W2; polyline( AP, AC, AW, 2, options); } segment() is merely a wrapper over polyline() , thus all options of segment() is the same as polyline(). Usage void sample_spectrum() { for ( int i=0; i < 20; i++) { Vec2 P1 = { 5+29.7*i, 187}; Vec2 P2 = { 35+29.7*i, 8}; Color C1 = { 1.0,0.0,0.5, 1.0}; Color C2 = { 0.5,0.0,1.0, 1.0}; double W1= 0.3*(i+1); double W2= W1; segment(P1,P2, C1,C2, W1,W2, 0); } } void sample_radial_spectrum() { for ( double ag=0, i=0; ag < 2*vaserend_pi-0.1; ag+=vaserend_pi/12, i+=1) { double r1 = 30.0; double r2 = 90.0; double tx2=r2*cos(ag); double ty2=r2*sin(ag); double tx1=r1*cos(ag); double ty1=r1*sin(ag); double Ox = 120; double Oy = 194+97; Vec2 P1 = { Ox+tx1,Oy-ty1}; Vec2 P2 = { Ox+tx2,Oy-ty2}; Color C1 = { 1.0,0.0,0.5, 1.0}; Color C2 = { 0.5,0.0,1.0, 1.0}; double W1= 0.3*(i+1); double W2= W1; segment(P1,P2, C1,C2, W1,W2, 0); } } example program is at samples/segment under VaseR package. In the below spectrums, each segment is 0.3 pixel thicker/ heavier than the previous segment, demonstrating sub- pixel accuracy of VaseR.

Source code

Development package with documentation, source code, sample images and sample programs is at sourceforge: current stable release or git source tree.

Credit and license

This library is no longer maintained, though I wish I could come back to 2d computer graphics some day.

The license terms at this version "Vase Renderer first draft, version 0.25 (draft1_2)" are:

The MIT License (MIT)
Copyright (c) 2011 Chris Tsang (tyt2y3@gmail.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.