June 28, 2011

vase_renderer_draft1_2

A newer version of VASE renderer is released.

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);
othergl'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.

2 comments:

  1. Great code, beautiful lines Chris. Thanks for this!

    Have you considered reworking it for OpenGL ES 2.0? Then it could be ported to WebGL and other ES2-only platforms.

    ReplyDelete
  2. Thanks for you comment.
    Actually, if you look into the source code, the only OpenGL dependent stuff is in vertex_array_holder.h, the draw() member function of class vertex_array_holder. Rest of the code is the computation of tessellation in pure C++. So, theoretically, it is easy for one to port the code to OpenGL ES.
    Unfortunately, my plan is to refine the code, making it more usable before consider porting.

    ReplyDelete