libgpac
Documentation of the core library of GPAC
Canvas3D Interface Reference

import"evg.idl";

+ Collaboration diagram for Canvas3D:

Public Member Functions

 Canvas3D (unsigned long width, unsigned long height, DOMString pixfmt)
 
 Canvas3D (unsigned long width, unsigned long height, DOMString pixfmt, ArrayBuffer data, optional unsigned long stride=0, optional unsigned long stride_uv=0)
 
void clear (IRect rc, unsigned long r, unsigned long g, unsigned long b, unsigned long a)
 
void clear (IRect rc, DOMString color)
 
void clear (IRect rc, DOMString color)
 
void clearf (IRect rc, double r, double g, double b, double a)
 
void clearf (IRect rc, DOMString color)
 
void reassign (ArrayBuffer data)
 
Object toRGB (optional bool as_array=false, Float y, Float u, Float v, optional Float a=1.0)
 
Object toRGB (optional bool as_array=false, Vec4f color)
 
Object toYUV (optional bool as_array=false, Float r, Float g, Float b, optional Float a=1.0)
 
Object toYUV (optional bool as_array=false, Vec4f color)
 
void projection (Float32Buffer projection_matrix)
 
void modelview (Float32Buffer modelview_matrix)
 
void draw_array (Int32Buffer indices, Float32Buffer vertices, optional GF_EVGPrimitiveType primitive_type=GF_EVG_TRIANGLES, optional long nb_components=3)
 
void draw_path (Path path, optional float z=0)
 
void draw_path (Text text, optional float z=0)
 
void clear_depth (float depth)
 
void viewport (long x, long y, long width, long height)
 
void viewport ()
 
Shader new_shader (ShaderType shader_type)
 

Data Fields

writeonly IRect clipper
 
Shader fragment
 
Shader vertex
 
writeonly boolean ccw
 
writeonly boolean backcull
 
writeonly boolean antialias
 
writeonly float min_depth
 
writeonly float max_depth
 
writeonly float point_size
 
writeonly boolean point_smooth
 
writeonly float line_size
 
writeonly boolean clip_zero
 
writeonly GF_EVGDepthTest depth_test
 
writeonly boolean write_depth
 
Float32Buffer depth_buffer
 

Detailed Description

The Canvas3D object is used to draw vectorial 3D meshes and 2D paths.

Warning
The 3D rasterizer is much much slower than WebGL as it is only software and not realy optimized, do not use it for complex 3D scenes.
The 3D rasterizer is still an experimental project: it might not be completely stable and its API may change a lot in the near future.

The 3D rasterizer can however be useful when drawing simple 3D objects over an existing video, as it avoids GPU transfers of the frame data.

The rasterizer supports:

  • points, lines, triangles, quads, strips and fans
  • 2D texturing using RGBA or YUVA colorspace
  • perspective correct interpolation
  • simple antialiasing
  • depth buffer (float only)
  • rasterizing in YUVA or RGBA space
  • a simple shading language for both vertex and fragment processing

The rasterizer does not claim compliancy to any GPU specification, and will likely produce different results than WebGL.

Constructor & Destructor Documentation

◆ Canvas3D() [1/2]

Canvas3D::Canvas3D ( unsigned long  width,
unsigned long  height,
DOMString  pixfmt 
)

Canvas3D constructor. The canvas memory is owned by the canvas object

Parameters
widththe width in pixels of the canvas
heightthe height in pixels of the canvas
pixfmtthe pixel fomat of the canvas

◆ Canvas3D() [2/2]

Canvas3D::Canvas3D ( unsigned long  width,
unsigned long  height,
DOMString  pixfmt,
ArrayBuffer  data,
optional unsigned long  stride = 0,
optional unsigned long  stride_uv = 0 
)

Canvas constructor

Parameters
widththe width in pixels of the canvas
heightthe height in pixels of the canvas
pixfmtthe pixel fomat of the canvas
datathe data buffer on which to write. The size shall be greater than the size required for the given size and pixel format.
stridehorizontal stride in pixel of the data
stride_uvhorizontal stride in pixel of the data for the U and V planes

Member Function Documentation

◆ clear() [1/3]

void Canvas3D::clear ( IRect  rc,
unsigned long  r,
unsigned long  g,
unsigned long  b,
unsigned long  a 
)

clears the canvas with the given color - see gf_evg_surface_clear

Note
Omitting the last values will assume 0xFF for alpha, and 0 for other values.
Parameters
rcthe rectangle to clear, in pixel coordinates
rred value, between 0 and 255
ggreen value, between 0 and 255
bblue value, between 0 and 255
aalpha value, between 0 and 255

◆ clear() [2/3]

void Canvas3D::clear ( IRect  rc,
DOMString  color 
)

clears the canvas with the given color. See gf_evg_surface_clear

Parameters
rcthe rectangle to clear, in pixel coordinates
coloran HTML/SVG color name or an HTML color value formated as $RRGGBB, #RRGGBB or 0xRRGGBB

◆ clear() [3/3]

void Canvas3D::clear ( IRect  rc,
DOMString  color 
)

clears the canvas with the given color. See gf_evg_surface_clear

Parameters
rcthe rectangle to clear, in pixel coordinates
coloran HTML/SVG color name or an HTML color value formated as $RRGGBB, #RRGGBB or 0xRRGGBB

◆ clearf() [1/2]

void Canvas3D::clearf ( IRect  rc,
double  r,
double  g,
double  b,
double  a 
)

clears the canvas with the given color

Note
Omitting the last values will assume 1.0 for alpha, and 0.0 for other values. See gf_evg_surface_clear
Parameters
rcthe rectangle to clear, in pixel coordinates
rred value, between 0.0 and 1.0
ggreen value, between 0.0 and 1.0
bblue value, between 0.0 and 1.0
aalpha value, between 0.0 and 1.0

◆ clearf() [2/2]

void Canvas3D::clearf ( IRect  rc,
DOMString  color 
)

clears the canvas with the given color. See gf_evg_surface_clear

Parameters
rcthe rectangle to clear, in pixel coordinates
coloran HTML/SVG color name or an HTML color value formated as $RRGGBB, #RRGGBB or 0xRRGGBB

◆ reassign()

void Canvas3D::reassign ( ArrayBuffer  data)

reassign internal data (typically at each new packet)

Warning
This assumes the data layout has not changed (width, height, pixel format, strides). If these are modified, create a new canvas.
Parameters
datathe buffer to use

◆ toRGB() [1/2]

Object Canvas3D::toRGB ( optional bool  as_array = false,
Float  y,
Float  u,
Float  v,
optional Float  a = 1.0 
)

converts YUV color to RGB

Parameters
as_arrayif true, the return object is an array of 4 components, otherwise it is a Vec4f object
yY component value
uCb/U component value
vCr/V component value
aalpha value, not modified
Returns
the converted value

◆ toRGB() [2/2]

Object Canvas3D::toRGB ( optional bool  as_array = false,
Vec4f  color 
)

converts YUV color to RGB

Parameters
as_arrayif true, the return object is an array of 4 components, otherwise it is a Vec4f object
colorthe YUV value to convert
Returns
the converted value

◆ toYUV() [1/2]

Object Canvas3D::toYUV ( optional bool  as_array = false,
Float  r,
Float  g,
Float  b,
optional Float  a = 1.0 
)

converts RGB color to YUV

Parameters
as_arrayif true, the return object is an array of 4 components, otherwise it is Vec4f object
rred component value
ggreen component value
bblue component value
aalpha value, not modified
Returns
the converted value

◆ toYUV() [2/2]

Object Canvas3D::toYUV ( optional bool  as_array = false,
Vec4f  color 
)

converts RGB color to YUV

Parameters
as_arrayif true, the return object is an array of 4 components, otherwise it is a Vec4f object
colorthe RGB value to convert
Returns
the converted value

◆ projection()

void Canvas3D::projection ( Float32Buffer  projection_matrix)

sets current projection matrix to use

Parameters
projection_matrixthe 16 float coeficients of the matrix, column-first. When using Matrix object, you can pass Matrix.m

◆ modelview()

void Canvas3D::modelview ( Float32Buffer  modelview_matrix)

sets current modelview matrix to use

Parameters
modelview_matrixthe 16 float coeficients of the matrix, column-first. When using Matrix object, you can pass Matrix.m

◆ draw_array()

void Canvas3D::draw_array ( Int32Buffer  indices,
Float32Buffer  vertices,
optional GF_EVGPrimitiveType  primitive_type = GF_EVG_TRIANGLES,
optional long  nb_components = 3 
)

draws a set of primitives (see gf_evg_surface_draw_array)

Parameters
indicesarray of indices in the vertex buffer for the primitives to draw
verticesthe vertices to use
primitive_typethe type of primitive to draw
nb_componentsthe number of components per vertex (eg, 2, 3)

◆ draw_path() [1/2]

void Canvas3D::draw_path ( Path  path,
optional float  z = 0 
)

draws a path (see gf_evg_surface_draw_path)

Parameters
paththe path to draw
zthe z value to assign to points in the path

◆ draw_path() [2/2]

void Canvas3D::draw_path ( Text  text,
optional float  z = 0 
)

draws a text (see gf_evg_surface_draw_path)

Parameters
textthe text to draw
zthe z value to assign to points in the text's path

◆ clear_depth()

void Canvas3D::clear_depth ( float  depth)

clears the depth buffer (see gf_evg_surface_clear_depth)

Parameters
depththe depth value to set

◆ viewport() [1/2]

void Canvas3D::viewport ( long  x,
long  y,
long  width,
long  height 
)

sets the viewport (see gf_evg_surface_viewport)

Parameters
xthe horizontal coordinate of the top-left corner of the viewport
ythe vertical coordinate of the top-left corner of the viewport
widththe width of the viewport
heightthe height of the viewport

◆ viewport() [2/2]

void Canvas3D::viewport ( )

sets the viewport to full canvas {0,0,width,height} (see gf_evg_surface_viewport)

◆ new_shader()

Shader Canvas3D::new_shader ( ShaderType  shader_type)

creats a new shader

Returns
the new shader
Parameters
shader_typethe desired shader type

Field Documentation

◆ clipper

writeonly IRect Canvas3D::clipper

clipper in pixel coordinates - see gf_evg_surface_set_clipper

Note
A same path can be drawn several times with different clipper, null means no clipper. Clipper applies to both fill and clear functions

◆ fragment

Shader Canvas3D::fragment

fragment shader to use, set to NULL to disable pixel writing.

◆ vertex

Shader Canvas3D::vertex

vertex shader to use, set to NULL to disable vertex shading, in which case the currently defined projection and modelview matrices will be used

◆ ccw

writeonly boolean Canvas3D::ccw

set face orientation to counter-clockwise or clockwise (see gf_evg_surface_set_ccw)

◆ backcull

writeonly boolean Canvas3D::backcull

backface culling enabled (see gf_evg_surface_set_backcull), default is true

◆ antialias

writeonly boolean Canvas3D::antialias

antialiased enabled (see gf_evg_surface_set_antialias), default is true

◆ min_depth

writeonly float Canvas3D::min_depth

min depth (see gf_evg_surface_set_min_depth), default is 0

◆ max_depth

writeonly float Canvas3D::max_depth

max depth (see gf_evg_surface_set_max_depth), default is 1.0

◆ point_size

writeonly float Canvas3D::point_size

point size (see gf_evg_surface_set_point_size), default is 1.0

◆ point_smooth

writeonly boolean Canvas3D::point_smooth

point smoothing enabled (see gf_evg_surface_set_point_smooth), default is false

◆ line_size

writeonly float Canvas3D::line_size

line size (see gf_evg_surface_set_line_size), default is 1.0

◆ clip_zero

writeonly boolean Canvas3D::clip_zero

clip zero enabled (see gf_evg_surface_set_clip_zero), default is false

◆ depth_test

writeonly GF_EVGDepthTest Canvas3D::depth_test

depth test mode (see gf_evg_set_depth_test), default is GF_EVGDEPTH_LESS

◆ write_depth

writeonly boolean Canvas3D::write_depth

write depth buffer enabled (see gf_evg_surface_write_depth), default is true

◆ depth_buffer

Float32Buffer Canvas3D::depth_buffer

depth buffer (see gf_evg_surface_set_depth_buffer).

Warning
Default is null