Commit 0e583b2c authored by Michele Bosi's avatar Michele Bosi

Updated Vivid Doxygen docs.

parent 2ace13e9
......@@ -70,7 +70,7 @@ VividRenderer::VividRenderer(VividRendering* vivid_rendering)
setEnableMask( Vivid::VividEnableMask );
// Depth peeling settings
mNumPasses = 4;
mDepthPeelingPasses = 4;
mUseQueryObject = false;
mQueryID = 0;
......@@ -495,7 +495,7 @@ void VividRenderer::renderFrontToBackPeeling(const RenderQueue* render_queue, Ca
bool throttle = 0 == translucent_count && mVividRendering->isDepthPeelingAutoThrottleEnabled();
GLuint samples_passed;
int numLayers = (mNumPasses - 1) * 2;
int numLayers = (mDepthPeelingPasses - 1) * 2;
for (int layer = 1; ! throttle && ( mUseQueryObject || layer < numLayers); layer++) {
int currId = layer % 2;
int prevId = 1 - currId;
......
......@@ -43,45 +43,40 @@ namespace vl
{
class VividRendering;
//-----------------------------------------------------------------------------
// VividRenderer
//-----------------------------------------------------------------------------
/** Experimental class. */
/**
* Implements a depth peeling rendering to be used by vl::VividRendering.
*/
class VLVIVID_EXPORT VividRenderer: public Renderer
{
VL_INSTRUMENT_CLASS(vl::VividRenderer, Renderer)
public:
// --- Renderer Implementation ---
VividRenderer(VividRendering* vivid_rendering);
virtual ~VividRenderer();
/** Takes as input the render queue to render and returns a possibly filtered render queue for further processing.
* VividRenderer's implementation of this function always returns \p in_render_queue. */
virtual const RenderQueue* render(const RenderQueue* in_render_queue, Camera* camera, real frame_clock);
/** Maximum number of passes to do if UseQueryObject is disabled (default is 6). */
void setNumPasses(int n) { mNumPasses = n; VL_CHECK(mNumPasses >= 1 && mNumPasses <= 100); }
/** Maximum number of passes to do if UseQueryObject is disabled (default is 6). */
int numPasses() const { return mNumPasses; }
//! Maximum number of passes to do if UseQueryObject is disabled (default is 4).
void setDetphPeelingPasses(int n) { mDepthPeelingPasses = n; VL_CHECK(mDepthPeelingPasses >= 1 && mDepthPeelingPasses <= 100); }
int depthPeelingPasses() const { return mDepthPeelingPasses; }
/** When enabled will use as many passes as needed to create a 100% correct rendering (disabled by default). */
//! When enabled will use as many passes as needed to create a 100% correct rendering (disabled by default).
void setUseQueryObject(bool use) { mUseQueryObject = use; }
/** When enabled will use as many passes as needed to create a 100% correct rendering (disabled by default). */
bool useQueryObject() const { return mUseQueryObject; }
/** The number of passes (renderQueue() calls) done for the last rendering including setup and finalization (may be > than NumPasses). */
int passCounter() const { return mPassCounter; }
void initShaders();
bool shadersReady() const;
//! Internal. Returns the depth texture used to access the depth buffer from the volume shader.
Texture* depthFBOTex() { return mDepthFBOTex.get(); }
const Texture* depthFBOTex() const { return mDepthFBOTex.get(); }
//! Internal. The background TextureSampler that contains the vl::Texture used to render the background
TextureSampler* backgroundTexSampler() { return mBackgroundTexSampler.get(); }
const TextureSampler* backgroundTexSampler() const { return mBackgroundTexSampler.get(); }
protected:
int passCounter() const { return mPassCounter; }
void initShaders();
bool shadersReady() const;
const RenderQueue* render(const RenderQueue* in_render_queue, Camera* camera, real frame_clock);
int renderQueue(const RenderQueue* in_render_queue, vl::GLSLProgram* cur_glsl, Camera* camera, real frame_clock, bool depth_peeling_on=true, bool outline_on = false);
void renderBackgroundImage( Camera* camera );
void render2DOutlines( const RenderQueue* in_render_queue, Camera* camera, real frame_clock );
......@@ -125,7 +120,7 @@ namespace vl
ref<TextureSampler> mBackgroundTexSampler;
int mPassCounter;
int mNumPasses;
int mDepthPeelingPasses;
bool mUseQueryObject;
GLuint mQueryID;
......
......@@ -42,71 +42,127 @@ namespace vl
{
namespace Vivid {
typedef enum {
//! Standard Vivid depth peeling rendering.
DepthPeeling,
//! Used for debugging.
FastRender,
//! Renders the stencil texture - used for debugging.
StencilRender
} ERenderingMode;
typedef enum {
//! This will use the Vivid depth peeling rendering path
//! Use this Actor enable mask to use the Vivid depth peeling rendering path.
//! Actors rendered with vl::Vivid::VividEnableMask require a vl::Effect created using vl::VividRendering::makeVividEffect().
VividEnableMask = 1,
//! This will use the standard VL Renderer rendering path. Used for volumes, text, etc.
//! Use this Actor enable mask to use the standard VL Renderer rendering path. Used for volumes, text, etc.
StandardEnableMask = 2
} EEnableMask;
typedef enum {
//! Texture unit reserved for Vivid usage.
TextureUnit0 = 0,
//! Texture unit reserved for Vivid usage.
TextureUnit1 = 1,
//! Texture unit reserved for Vivid usage.
TextureUnit2 = 2,
//! Texture unit reserved for Vivid usage.
TextureUnit3 = 3,
//! Texture unit usable by the user. We only support one texture at the moment.
UserTexture = 4
} ETextureUnits;
typedef enum {
//! Direct volume rendering.
Direct,
//! Isosurface volume rendering.
Isosurface,
//! MIP volume rendering.
MIP
} EVolumeMode;
typedef enum {
//! 3D point representation used by niftk::VLMapperPoints
Point3D,
//! 2D point representation used by niftk::VLMapperPoints
Point2D
} EPointMode;
typedef enum {
//! Color "smart" target for Vivid fog and clipping settings.
Color,
//! Alpha "smart" target for Vivid fog and clipping settings.
Alpha,
//! Saturation "smart" target for Vivid fog and clipping settings.
Saturation
} ESmartTarget;
typedef enum {
//! Disables fog
FogOff,
//! Use linear fog equation
FogLinear,
//! Use exp fog equation
FogExp,
//! Use exp2 fog equation
FogExp2
} EFogMode;
typedef enum {
//! Disables a clipping unit
ClipOff,
//! Enables sphere clipping
ClipSphere,
//! Enables box clipping
ClipBox,
//! Enables plane clipping
ClipPlane
} EClipMode;
typedef enum {
//! Renders a 3D surface (default)
//! \sa niftk::VLMapper::setRenderingMode()
Polys,
//! Renders the 3D outline of a 3D surface (default)
//! \sa niftk::VLMapper::setRenderingMode()
Outline3D,
//! Renders the polygons and 3D outline of a 3D surface (default)
//! \sa niftk::VLMapper::setRenderingMode()
PolysAndOutline3D,
//! Renders the 3D clipping outline of a 3D surface (default)
//! \sa niftk::VLMapper::setRenderingMode()
Slice,
//! Renders the 2D outline of a 3D surface (default)
Outline2D,
//! Renders the polygons and 2D outline of a 3D surface (default)
//! \sa niftk::VLMapper::setRenderingMode()
PolysAndOutline2D,
} ESurfaceMode;
}
//-----------------------------------------------------------------------------
// VividRendering
//-----------------------------------------------------------------------------
/** Experimental class. */
/**
* vl::VividRendering implements a "rendering engine" with a pipeline and features specifically designed around NifTK needs.
*
* vl::VividRendering differs from vl::Rendering in that vl::Rendering is designed as a general purpose rendering engine
* supporting all standard OpenGL features & render states like Material, ColorMaterial, Light, 3D textures etc.,
* while vl::VividRendering supports a much smaller subset of standard OpenGL render states but supports out of the box
* some key features specific to NifTK like animated background, depth peeling, 2D & 3D outlines, smart clipping,
* smart fogging, 3D stencil, camera calibration etc.
*
* Most of these new features are driven either by options here in the vl::VividRendering class or as Uniform variables
* in the Actor's Effect. Such Uniform variables are initialized by the vl::VividRendering::makeVividEffect().
* The ultimate reference to which Uniform variable does what is the /vivid/glsl/uniforms.glsl file included in most GLSL
* shaders. Secondly vl::VividRendering::makeVividEffect()'s source code will show their default values and some extra description.
*
* The bulk of the rendering engine is implemented by the vl::ViviRenderer around a depth peeling rendering core.
*
* Actors added to the vl::VividRendering::sceneManager() can be rendered by either vl::ViviRenderer when using
* vl::Actors::setEnableMask( vl::Vivid::VividEnableMask ) or by the standard vl::Renderer using
* vl::Actors::setEnableMask( vl::Vivid::StandadrdEnableMask ). This is useful when rendering objects using render states
* not supported by the VividRenderer. The rendering pipeline always draws vl::Vivid::VividEnableMask objects first and
* then vl::Vivid::StandadrdEnableMask ones after.
*
* Actors rendered with vl::Vivid::VividEnableMask requires a vl::Effect created using vl::VividRendering::makeVividEffect().
*/
class VLVIVID_EXPORT VividRendering: public Rendering
{
VL_INSTRUMENT_CLASS(vl::VividRendering, Rendering)
......@@ -114,96 +170,109 @@ namespace vl
public:
VividRendering();
//! Renders the scene on the given framebuffer
void render( Framebuffer* framebuffer ) { vividRenderer()->setFramebuffer(framebuffer); Rendering::render(); }
VividRenderer* vividRenderer() { return mVividRenderer.get(); }
const VividRenderer* vividRenderer() const { return mVividRenderer.get(); }
//! Returns the default vl::CalibratedCamera
CalibratedCamera* calibratedCamera() { return mCalibratedCamera.get(); }
const CalibratedCamera* calibratedCamera() const { return mCalibratedCamera.get(); }
//! Returns the default vl::SceneManagerActorTree
SceneManagerActorTree* sceneManager() { return mSceneManagerActorTree.get(); }
const SceneManagerActorTree* sceneManager() const { return mSceneManagerActorTree.get(); }
// Settings
// --- Settings ---
//! Sets the global rendering mode, used for debuggig purposes.
void setRenderingMode(Vivid::ERenderingMode mode) { mRenderingMode = mode; }
Vivid::ERenderingMode renderingMode() const { return mRenderingMode; }
/** The opacity of the 3D rendering on top of the background. */
//! Sets the number of depth peeling passes.
//! The more passes the more transparency layers will be visible.
//! Each transparency layer requires an additional rendering of the scene so the higher the number the slower the rendering.
//! \sa setDepthPeelingAutoThrottleEnabled()
void setDepthPeelingPasses( int n ) { mVividRenderer->setDetphPeelingPasses( n ); }
int depthPeelingPasses() const { return mVividRenderer->depthPeelingPasses(); }
//! Allows depth peeling to be disabled for a faster rendering using a simple test.
//! This works in the simplest but usual cases where:
//! - Lighting is enabled and material diffuse alpha is == 1
//! - Outline color alpha is == 1
//! - All vertex colors alphas are == 1
//! - Texture has either completely opaque or completely transparent texels (point sprites, alpha masking etc.)
//! - Point sprites may look a bit rough
//! Does not detect:
//! - Some but not all vertex color alphas are < 1
//! - Texture has translucent texels, ie 0 < alpha < 1 (as opposed to either 0 or 1)
void setDepthPeelingAutoThrottleEnabled( bool enabled ) { m_DepthPeelingAutoThrottleEnabled = enabled; }
bool isDepthPeelingAutoThrottleEnabled() const { return m_DepthPeelingAutoThrottleEnabled; }
//!! The opacity of the overall 3D rendering on top of the background. The background is always fully opaque.
void setOpacity( float a ) { mOpacity = a; }
/** The opacity of the 3D rendering on top of the background. */
float opacity() const { return mOpacity; }
// Outline settings
// --- Outline Settings ---
/** Offset outline by given amount in camera space to make it more visible. Only for `Outline3D` modes. */
//! Advanced. Offset outline by given amount in camera space to make it more visible. Only for `Outline3D` modes.
void setOutline3DEyeOffset( float offset ) { mOutline3DEyeOffset = offset; }
/** Offset outline by given amount in camera space to make it more visible. Only for `Outline3D` modes. */
float outline3DEyeOffset() const { return mOutline3DEyeOffset; }
/** Offset outline by given amount in NDC space to make it more visible. Only for `Outline3D` modes. */
// Advanced. Offset outline by given amount in NDC space to make it more visible. Only for `Outline3D` modes.
void setOutline3DClipOffset( float offset ) { mOutline3DClipOffset = offset; }
/** Offset outline by given amount in NDC space to make it more visible. Only for `Outline3D` modes. */
float outline3DClipOffset() const { return mOutline3DClipOffset; }
// Stencil settings
// --- Stencil Settings ---
/** Enable/disable Stencil Rendering mode. */
//! Enable/disable Stencil Rendering mode.
void setStencilEnabled( bool enabled ) { mStencilEnabled = enabled; }
/** Enable/disable Stencil Rendering mode. */
bool isStencilEnabled() const { return mStencilEnabled; }
/** Background color used when stencil rendering mode is enabled. */
//! Background color used when stencil rendering mode is enabled.
//! Stencil background color cannot be transparent at the moment.
void setStencilBackgroundColor( const vec4& color) { mStencilBackground = color; }
/** Background color used when stencil rendering mode is enabled. */
const vec4& stencilBackgroundColor() const { return mStencilBackground; }
/** The Actors containing Geometry used to render into the Stencil Texture. */
//! The Actors used to render into the Stencil Texture.
std::vector< ref<Actor> >& stencilActors() { return mStencilActors; }
/** The Actors containing Geometry used to render into the Stencil Texture. */
const std::vector< ref<Actor> >& stencilActors() const { return mStencilActors; }
/** Stencil Texture smoothness, ie. the size of the blur kernel, default is 10. Larger values take longer to compute. */
//! Stencil Texture smoothness, ie. the size of the blur kernel, default is 10. Larger values take longer to compute.
//! See also this issue: https://cmiclab.cs.ucl.ac.uk/CMIC/NifTK/issues/4717
void setStencilSmoothness( int smoothness ) { mStencilSmoothness = smoothness; }
/** Stencil Texture smoothness, ie. the size of the blur kernel, default is 10. Larger values take longer to compute. */
int stencilSmoothness() const { return mStencilSmoothness; }
// Background settings
// --- Background Settings ---
//! The background color
void setBackgroundColor( const vec4& color ) { camera()->viewport()->setClearColor( color ); }
const vec4& backgroundColor() const { return camera()->viewport()->clearColor(); }
//! Enable/disable the background image
void setBackgroundImageEnabled( bool enabled ){ mBackgroundImageEnabled = enabled; }
bool backgroundImageEnabled() const { return mBackgroundImageEnabled; }
//! Internal. The background TextureSampler that contains the vl::Texture used to render the background
TextureSampler* backgroundTexSampler() { return mVividRenderer->backgroundTexSampler(); }
const TextureSampler* backgroundTexSampler() const { return mVividRenderer->backgroundTexSampler(); }
// Allow depth peeling to be disabled for a faster rendering using a simple test.
// This works in the simplest but usual cases where:
// - Lighting is on and material diffuse alpha is < 1
// - Outline color alpha is < 1
// - All vertex colors alphas are < 1
// - Texture has transparent texels, ie alpha == 0 (point sprites, alpha masking etc.)
// - Point sprites may look a bit rough
// Does not detect:
// - Some but not all vertex color alphas are < 1
// - Texture has translucent texels, ie 0 < alpha < 1 (as opposed to 0 <= alpha <= 1)
void setDepthPeelingAutoThrottleEnabled( bool enabled ) { m_DepthPeelingAutoThrottleEnabled = enabled; }
bool isDepthPeelingAutoThrottleEnabled() const { return m_DepthPeelingAutoThrottleEnabled; }
// Utils
// --- Vivid Effect ---
/** Returns an Effect that is compatible with the Vivid renderer and set to all its defaults.
\param effect If != NULL it will initialize the input effect else a new one will be returned. */
//! Returns an Effect that is compatible with vl::VividRenderer.
//! All Actors with vl::Vivid::VividEnableMask are required to have an Effect created by this function.
//! \param effect If != NULL it will initialize the input effect else a new one will be returned.
static ref<Effect> makeVividEffect( Effect* effect = NULL );
// Internal
// --- Internal ---
//! Internal. Used by vl::VividVolume.
Texture* depthFBOTex() { return mVividRenderer->depthFBOTex(); }
//! Internal. Used by vl::VividVolume.
const Texture* depthFBOTex() const { return mVividRenderer->depthFBOTex(); }
protected:
VividRenderer* vividRenderer() { return mVividRenderer.get(); }
const VividRenderer* vividRenderer() const { return mVividRenderer.get(); }
private:
ref< VividRenderer > mVividRenderer;
ref< CalibratedCamera > mCalibratedCamera;
......
......@@ -40,11 +40,12 @@ namespace vl
{
class VividRendering;
/** Main class used to manage a volume rendered by VividRendering.
/**
* Used to setup and manages a volume rendering within a vl::VividRendering.
*
* Features:
* - High quality ray-marching based rendering
* - Direct, Isosurface (even transparent) and MIP modes
* - Direct, Isosurface (incl. transparent) and MIP modes
* - Proper intersections with opaque objects via special VividRendering depth buffer
* - Supports rectangular volumes
* - Can have an associate Transform with arbitrary rotation and translation (not scaling)
......@@ -52,10 +53,11 @@ namespace vl
* - Fast rendering using pre-computed high quality gradient texture
* - Fast and arbitrary RGBA transfer function via 1D texture lookup
*
* Improvements:
* - Support nested volumes (limit is the number of texture units available)
* Whish List:
* - Support nested & intersecting volumes
* - Adaptive ray-step: adapt ray sampling step to size of volume on the screen and distance from viewer (a la mip-mapping) producing a faster and higher quality rendering.
* - Advanced lighting, shadows, scattering etc. */
* - Advanced lighting, shadows, scattering etc.
*/
class VLVIVID_EXPORT VividVolume: public ActorEventCallback
{
VL_INSTRUMENT_CLASS(vl::VividVolume, ActorEventCallback)
......@@ -69,47 +71,44 @@ namespace vl
public:
VividVolume(VividRendering* vivid_rendering);
/** Initializes all the volume data, uniforms and textures.
This function is called by VividRendering::setupVolume(), which is the one you want to use usually.
\param volume The 3D image representing the volume, typcally of IF_LUMINANCE format.
\param volume_bounds The AABB of the volume, can be a rectangle and defines the object space dimensions of the volume.
\param transfer_function A 1D image representing the RGBA values associated to a given `luminance` value (used by all modes).
*/
//! Initializes all the volume data, uniforms and textures.
//!
//! \param volume The 3D image representing the volume, typcally of IF_LUMINANCE format.
//! \param volume_bounds The AABB of the volume, can be a rectangle and defines the object space dimensions of the volume.
//! \param transfer_function A 1D image representing the RGBA values associated to a given `luminance` value (used by all modes).
void setupVolume( Image* volume, const AABB& volume_bounds, Image* transfer_function);
/** Direct, Isosurface, MIP */
//! Select volume rendering mode: Direct, Isosurface, MIP
void setVolumeMode( EVolumeMode mode ) { mVolumeMode = mode; }
/** Direct, Isosurface, MIP */
EVolumeMode volumeMode() { return mVolumeMode; }
/** Only used in Isosurface mode. */
//! Iso value for Isosurface mode.
void setIsoValue( float iso ) { mIsoValue = iso; }
/** Only used in Isosurface mode. */
float isoValue() const { return mIsoValue; }
/** Maximum number of samples to take for each ray. The higher the samples the higher the quality of the rendering (at the expense of rendering time). */
//! Maximum number of samples to take along each ray. The higher the samples the higher the quality of the rendering (at the expense of rendering time).
void setSamplesPerRay( int samples ) { mSamplesPerRay = samples; }
/** Maximum number of samples to take for each ray. The higher the samples the higher the quality of the rendering (at the expense of rendering time). */
int samplesPerRay() const { return mSamplesPerRay; }
/** Only used in Direct mode. */
//! The density of the volume. Only used in Direct mode.
void setVolumeDensity( float density ) { mVolumeDensity = density; }
/** Only used in Direct mode. */
float volumeDensity() const { return mVolumeDensity; }
//! The Actor to which the volume is attached. Used to enable/disable the Actor and modify the Transform.
Actor* volumeActor() { return mVolumeActor.get(); }
const Actor* volumeActor() const { return mVolumeActor.get(); }
//! The Transform to which the volume is attached.
Transform* volumeTransform() { return mVolumeTransform.get(); }
const Transform* volumeTransform() const { return mVolumeTransform.get(); }
//! The Effect used to render the volume, usually you don't need to touch this.
Effect* volumeFX() { return mVolumeFX.get(); }
const Effect* volumeFX() const { return mVolumeFX.get(); }
//! The GLSLProgram used to render the volume, usually you don't need to touch this.
GLSLProgram* volumeGLSLProgram() { return mVolumeGLSLProgram.get(); }
const GLSLProgram* volumeGLSLProgram() const { return mVolumeGLSLProgram.get(); }
Transform* volumeTransform() { return mVolumeTransform.get(); }
const Transform* volumeTransform() const { return mVolumeTransform.get(); }
protected:
......@@ -119,38 +118,38 @@ namespace vl
virtual void onActorDelete( Actor* ) {}
/** Binds a VividVolume to an Actor. */
//! Binds a VividVolume to an Actor.
void bindActor( Actor* );
/** Updates the uniforms used by the GLSLProgram to render the volume each time the onActorRenderStarted() method is called. */
//! Updates the uniforms used by the GLSLProgram to render the volume each time the onActorRenderStarted() method is called.
void updateUniforms( Actor* actor, real clock, const Camera* camera, Renderable* rend, const Shader* shader );
/** Returns the Geometry associated to a VividVolume and its bound Actor. */
//! Returns the Geometry associated to a VividVolume and its bound Actor.
Geometry* geometry() { return mGeometry.get(); }
/** Returns the Geometry associated to a VividVolume and its bound Actor. */
//! Returns the Geometry associated to a VividVolume and its bound Actor.
const Geometry* geometry() const { return mGeometry.get(); }
/** Defines the dimensions of the box in model coordinates enclosing the volume and generates the actual geometry of the box to be rendered. */
//! Defines the dimensions of the box in model coordinates enclosing the volume and generates the actual geometry of the box to be rendered.
void setBox( const AABB& box );
/** The dimensions of the box enclosing the volume. */
//! The dimensions of the box enclosing the volume.
const AABB& box() const { return mBox; }
/** Returns the coordinates assigned to each of the 8 box corners of the volume. */
//! Returns the coordinates assigned to each of the 8 box corners of the volume.
const fvec3* vertCoords() const { return mVertCoord->begin(); }
/** Returns the coordinates assigned to each of the 8 box corners of the volume. */
//! Returns the coordinates assigned to each of the 8 box corners of the volume.
fvec3* vertCoords() { return mVertCoord->begin(); }
/** Returns the texture coordinates assigned to each of the 8 box corners of the volume. */
//! Returns the texture coordinates assigned to each of the 8 box corners of the volume.
const fvec3* texCoords() const { return mTexCoord->begin(); }
/** Returns the texture coordinates assigned to each of the 8 box corners of the volume. */
//! Returns the texture coordinates assigned to each of the 8 box corners of the volume.
fvec3* texCoords() { return mTexCoord->begin(); }
/** Generates a default set of texture coordinates for the 8 box corners of the volume based on the given texture dimensions.
\param img_size Size in texels of the volume texture. */
//! Generates a default set of texture coordinates for the 8 box corners of the volume based on the given texture dimensions.
//! \param img_size Size in texels of the volume texture.
void generateTextureCoordinates( const ivec3& img_size );
protected:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment