Enabling this option makes Cogl trace how the journal is managing to batch
your rectangles. The journal staggers how it emmits state to the GL driver
and the batches will normally get smaller for each stage, but ideally you
don't want to be in a situation where Cogl is only able to draw one quad per
modelview change and draw call.
E.g. this is a fairly ideal example:
BATCHING: journal len = 101
BATCHING: vbo offset batch len = 101
BATCHING: material batch len = 101
BATCHING: modelview batch len = 101
This isn't:
BATCHING: journal len = 1
BATCHING: vbo offset batch len = 1
BATCHING: material batch len = 1
BATCHING: modelview batch len = 1
BATCHING: journal len = 1
BATCHING: vbo offset batch len = 1
BATCHING: material batch len = 1
BATCHING: modelview batch len = 1
<repeat>
When this option is used Cogl will print a trace of all quads that get
logged into the journal, and a trace of quads as they get flushed.
If you are seeing a bug with the geometry being drawn by Cogl this may give
some clues by letting you sanity check the numbers being logged vs the
numbers being emitted.
For testing the VBO fallback paths it helps to be able to disable the
COGL_FEATURE_VBOS feature flag. When VBOs aren't available Cogl should use
client side malloc()'d buffers instead.
Previously the journal was always flushed at the end of
_cogl_rectangles_with_multitexture_coords, (i.e. the end of any
cogl_rectangle* calls) but now we have broadened the potential for batching
geometry. In ideal circumstances we will only flush once per scene.
In summary the journal works like this:
When you use any of the cogl_rectangle* APIs then nothing is emitted to the
GPU at this point, we just log one or more quads into the journal. A
journal entry consists of the quad coordinates, an associated material
reference, and a modelview matrix. Ideally the journal only gets flushed
once at the end of a scene, but in fact there are things to consider that
may cause unwanted flushing, including:
- modifying materials mid-scene
This is because each quad in the journal has an associated material
reference (i.e. not copy), so if you try and modify a material that is
already referenced in the journal we force a flush first)
NOTE: For now this means you should avoid using cogl_set_source_color()
since that currently uses a single shared material. Later we
should change it to use a pool of materials that is recycled
when the journal is flushed.
- modifying any state that isn't currently logged, such as depth, fog and
backface culling enables.
The first thing that happens when flushing, is to upload all the vertex data
associated with the journal into a single VBO.
We then go through a process of splitting up the journal into batches that
have compatible state so they can be emitted to the GPU together. This is
currently broken up into 3 levels so we can stagger the state changes:
1) we break the journal up according to changes in the number of material layers
associated with logged quads. The number of layers in a material determines
the stride of the associated vertices, so we have to update our vertex
array offsets at this level. (i.e. calling gl{Vertex,Color},Pointer etc)
2) we further split batches up according to material compatability. (e.g.
materials with different textures) We flush material state at this level.
3) Finally we split batches up according to modelview changes. At this level
we update the modelview matrix and actually emit the actual draw command.
This commit is largely about putting the initial design in-place; this will be
followed by other changes that take advantage of the extended batching.
Setting up layer combine functions and blend modes is very awkward to do
programatically. This adds a parser for string based descriptions which are
more consise and readable.
E.g. a material layer combine function could now be given as:
"RGBA = ADD (TEXTURE[A], PREVIOUS[RGB])"
or
"RGB = REPLACE (PREVIOUS)"
"A = MODULATE (PREVIOUS, TEXTURE)"
The simple syntax and grammar are only designed to expose standard fixed
function hardware, more advanced combining must be done with shaders.
This includes standalone documentation of blend strings covering the aspects
that are common to blending and texture combining, and adds documentation
with examples specific to the new cogl_material_set_blend() and
cogl_material_layer_set_combine() functions.
Note: The hope is to remove the now redundant bits of the material API
before 1.0
Currently, COGL depends on defining debug symbols by manually
modifying the source code. When it's done, it will forcefully
print stuff to the console.
Since COGL has also a pretty, runtime selectable debugging API
we might as well switch everything to it.
In order for this to happen, configure needs a new:
--enable-cogl-debug
command line switch; this will enable COGL debugging, the
CoglHandle debugging and will also turn on the error checking
for each GL operation.
The default setting for the COGL debug defines is off, since
it slows down the GL operations; enabling it for a particular
debug build is trivial, though.
Adds missing notices, and ensures all the notices are consistent. The Cogl
blurb also now reads:
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
This makes the #if 0'd debug code that was in _cogl_journal_flush_quad_batch
- which we have repeatedly found usefull for debugging various geometry
issues in Clutter apps - a runtime debug option.
The outline colors rotate in order from red to green to blue which can also
help confirm the order that your geometry really drawn.
The outlines are not affected by the current material state, so if you e.g.
have a blending bug where geometry mysteriously disappears this can confirm
if the underlying rectangles are actually being emitted but blending is
causing them to be invisible.
The CoglPango code falls under the COGL "jurisdiction"; this means
that it cannot include Clutter headers unless strictly necessary.
The CoglPangoRenderer code was using the CLUTTER_NOTE() macro. Now
that COGL has it's own COGL_NOTE() similar macro, CoglPango should
use that and avoid including clutter-debug.h (which pulls in
clutter-private.h which in turn pulls in clutter-actor.h).
A new flag, COGL_DEBUG_PANGO, has been added to the COGL debug
flags.
Clutter is able to show debug messages written using the CLUTTER_NOTE()
macro at runtime, either by using an environment variable:
CLUTTER_DEBUG=...
or by using a command line switch:
--clutter-debug=...
--clutter-no-debug=...
Both are parsed during the initialization process by using the
GOption API.
COGL would benefit from having the same support.
In order to do this, we need a cogl_get_option_group() function in
COGL that sets up a GOptionGroup for COGL and adds a pre-parse hook
that will check the COGL_DEBUG environment variable. The OptionGroup
will also install two command line switches:
--cogl-debug
--cogl-no-debug
With the same semantics of the Clutter ones.
During Clutter initialization, the COGL option group will be attached
to the GOptionContext used to parse the command line options passed
to a Clutter application.
Every debug message written using:
COGL_NOTE (SECTION, "message format", arguments);
Will then be printed only if SECTION was enabled at runtime.
This whole machinery, like the equivalent one in Clutter, depends on
a compile time switch, COGL_ENABLE_DEBUG, which is enabled at the same
time as CLUTTER_ENABLE_DEBUG. Having two different symbols allows
greater granularity.
