diff options
author | Robert Bragg <robert@linux.intel.com> | 2011-08-23 13:55:12 +0100 |
---|---|---|
committer | Robert Bragg <robert@linux.intel.com> | 2011-10-28 19:10:16 +0100 |
commit | dd7b16faf2cc85c29159442b42ed3f7f46a4dd71 (patch) | |
tree | c053ec5f404ec970f64af008f9963753aced71d7 /cogl/cogl-framebuffer.h | |
parent | a74c81ada38d0a38ab3b4566b20ee4370a032eeb (diff) | |
download | cogl-dd7b16faf2cc85c29159442b42ed3f7f46a4dd71.tar.gz |
offscreen: Adds support for offscreen multisampling
This adds support for multisample rendering to offscreen framebuffers.
After an offscreen framebuffer is first instantiated using
cogl_offscreen_new_to_texture() it is then possible to use
cogl_framebuffer_set_samples_per_pixel() to request multisampling before
the framebuffer is allocated. This also adds
cogl_framebuffer_resolve_samples() for explicitly resolving point
samples into pixels. Even though we currently only support the
IMG_multisampled_render_to_texture extension which doesn't require an
explicit resolve, the plan is to also support the
EXT_framebuffer_multisample extension which uses the framebuffer_blit
extension to issue an explicit resolve.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
Diffstat (limited to 'cogl/cogl-framebuffer.h')
-rw-r--r-- | cogl/cogl-framebuffer.h | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h index 616cfbde..ad4d1e4e 100644 --- a/cogl/cogl-framebuffer.h +++ b/cogl/cogl-framebuffer.h @@ -277,6 +277,128 @@ cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer, CoglPixelFormat cogl_framebuffer_get_color_format (CoglFramebuffer *framebuffer); +#define cogl_framebuffer_set_samples_per_pixel \ + cogl_framebuffer_set_samples_per_pixel_EXP +/** + * cogl_framebuffer_set_samples_per_pixel: + * @framebuffer: A #CoglFramebuffer framebuffer + * @n: The minimum number of samples per pixel + * + * Requires that when rendering to @framebuffer then @n point samples + * should be made per pixel which will all contribute to the final + * resolved color for that pixel. The idea is that the hardware aims + * to get quality similar to what you would get if you rendered + * everything twice as big (for 4 samples per pixel) and then scaled + * that image back down with filtering. It can effectively remove the + * jagged edges of polygons and should be more efficient than if you + * were to manually render at a higher resolution and downscale + * because the hardware is often able to take some shortcuts. For + * example the GPU may only calculate a single texture sample for all + * points of a single pixel, and for tile based architectures all the + * extra sample data (such as depth and stencil samples) may be + * handled on-chip and so avoid increased demand on system memory + * bandwidth. + * + * By default this value is usually set to 0 and that is referred to + * as "single-sample" rendering. A value of 1 or greater is referred + * to as "multisample" rendering. + * + * <note>There are some semantic differences between single-sample + * rendering and multisampling with just 1 point sample such as it + * being redundant to use the cogl_framebuffer_resolve_samples() and + * cogl_framebuffer_resolve_samples_region() apis with single-sample + * rendering.</note> + * + * <note>It's recommended that + * cogl_framebuffer_resolve_samples_region() be explicitly used at the + * end of rendering to a point sample buffer to minimize the number of + * samples that get resolved. By default Cogl will implicitly resolve + * all framebuffer samples but if only a small region of a + * framebuffer has changed this can lead to redundant work being + * done.</note> + * + * Since: 1.8 + * Stability: unstable + */ +void +cogl_framebuffer_set_samples_per_pixel (CoglFramebuffer *framebuffer, + int samples_per_pixel); + +#define cogl_framebuffer_resolve_samples \ + cogl_framebuffer_resolve_samples_EXP +/** + * cogl_framebuffer_resolve_samples: + * @framebuffer: A #CoglFramebuffer framebuffer + * + * When point sample rendering (also known as multisample rendering) + * has been enabled via cogl_framebuffer_set_samples_per_pixel() + * then you can optionally call this function (or + * cogl_framebuffer_resolve_samples_region()) to explicitly resolve + * the point samples into values for the final color buffer. + * + * Some GPUs will implicitly resolve the point samples during + * rendering and so this function is effectively a nop, but with other + * architectures it is desirable to defer the resolve step until the + * end of the frame. + * + * Since Cogl will automatically ensure samples are resolved if the + * target color buffer is used as a source this API only needs to be + * used if explicit control is desired - perhaps because you want to + * ensure that the resolve is completed in advance to avoid later + * having to wait for the resolve to complete. + * + * If you are performing incremental updates to a framebuffer you + * should consider using cogl_framebuffer_resolve_samples_region() + * instead to avoid resolving redundant pixels. + * + * Since: 1.8 + * Stability: unstable + */ +void +cogl_framebuffer_resolve_samples (CoglFramebuffer *framebuffer); + +#define cogl_framebuffer_resolve_samples_region \ + cogl_framebuffer_resolve_samples_region_EXP +/** + * cogl_framebuffer_resolve_samples_region: + * @framebuffer: A #CoglFramebuffer framebuffer + * @x: top-left x coordinate of region to resolve + * @y: top-left y coordinate of region to resolve + * @width: width of region to resolve + * @height: height of region to resolve + * + * When point sample rendering (also known as multisample rendering) + * has been enabled via cogl_framebuffer_set_samples_per_pixel() + * then you can optionally call this function (or + * cogl_framebuffer_resolve_samples()) to explicitly resolve the point + * samples into values for the final color buffer. + * + * Some GPUs will implicitly resolve the point samples during + * rendering and so this function is effectively a nop, but with other + * architectures it is desirable to defer the resolve step until the + * end of the frame. + * + * Use of this API is recommended if incremental, small updates to + * a framebuffer are being made because by default Cogl will + * implicitly resolve all the point samples of the framebuffer which + * can result in redundant work if only a small number of samples have + * changed. + * + * Because some GPUs implicitly resolve point samples this function + * only guarantees that at-least the region specified will be resolved + * and if you have rendered to a larger region then it's possible that + * other samples may be implicitly resolved. + * + * Since: 1.8 + * Stability: unstable + */ +void +cogl_framebuffer_resolve_samples_region (CoglFramebuffer *framebuffer, + int x, + int y, + int width, + int height); + #define cogl_framebuffer_get_context cogl_framebuffer_get_context_EXP /** * @framebuffer: A #CoglFramebuffer @@ -598,6 +720,19 @@ cogl_get_draw_framebuffer (void); #endif /* COGL_ENABLE_EXPERIMENTAL_API */ +/* XXX: Note these are defined outside the COGL_ENABLE_EXPERIMENTAL_API guard since + * otherwise the glib-mkenums stuff will get upset. */ + +#define cogl_framebuffer_error_quark cogl_framebuffer_error_quark_EXP +GQuark +cogl_framebuffer_error_quark (void); + +#define COGL_FRAMEBUFFER_ERROR (cogl_framebuffer_error_quark ()) + +typedef enum { /*< prefix=COGL_FRAMEBUFFER_ERROR >*/ + COGL_FRAMEBUFFER_ERROR_ALLOCATE +} CoglFramebufferError; + G_END_DECLS #endif /* __COGL_FRAMEBUFFER_H */ |