The Lines class provides an abstraction for rendering 3D lines with variable thickness and different implementation strategies. More...

#include <vclib/bgfx/primitives/lines.h>

Inheritance diagram for vcl::Lines:

[legend]

Public Types
enum class	ColorToUse { PER_VERTEX , PER_EDGE , GENERAL }

enum class	ImplementationType { PRIMITIVE = 0 , CPU_GENERATED = 1 , COUNT }

Public Member Functions
ColorToUse	colorToUse () const
	Returns the color that is used to render the lines.

void	draw (uint viewId) const
	Draws in the given view the lines with the current settings.

Color &	generalColor ()
	Returns a reference to the general color that is used to render the lines when colorToUse() is set to ColorToUse::GENERAL. This allows to modify the color directly.

Color	generalColor () const
	Returns the general color that is used to render the lines when colorToUse() is set to ColorToUse::GENERAL.

ImplementationType	implementationType () const
	Returns the current implementation type that is used to render the lines.

	Lines (const std::vector< float > &vertCoords, const std::vector< float > &vertNormals, const std::vector< uint > &vertColors, const std::vector< uint > &lineColors, float thickness=5.0f, bool shadingPerVertex=false, ColorToUse colorToUse=ColorToUse::GENERAL, ImplementationType type=ImplementationType::COUNT)
	Creates a Lines object with given points and parameters.

	Lines (const std::vector< float > &vertCoords, const std::vector< uint > &lineIndices, const std::vector< float > &vertNormals, const std::vector< uint > &vertColors, const std::vector< uint > &lineColors, float thickness=5.0f, bool shadingPerVertex=false, ColorToUse colorToUse=ColorToUse::GENERAL, ImplementationType type=ImplementationType::COUNT)
	Creates a Lines object with given points and parameters.

	Lines (ImplementationType type=ImplementationType::COUNT)
	Creates a Lines object with default parameters and without points.

void	setColorToUse (ColorToUse color)
	Sets which color to use for rendering the lines.

void	setPoints (const std::vector< float > &vertCoords, const std::vector< float > &vertNormals, const std::vector< uint > &vertColors, const std::vector< uint > &lineColors, ImplementationType type=ImplementationType::COUNT)
	Sets the points of the lines.

void	setPoints (const std::vector< float > &vertCoords, const std::vector< uint > &lineIndices, const std::vector< float > &vertNormals, const std::vector< uint > &vertColors, const std::vector< uint > &lineColors, ImplementationType type=ImplementationType::COUNT)
	Sets the points of the lines.

void	setShading (bool perVertex)
	Sets wether to use per vertex shading (using vertex normals) or not.

bool	shadingPerVertex () const
	Returns true if shading is computed per vertex using vertex normals, false if no shading is applied.

float &	thickness ()
	Returns a reference to the thickness of the lines (in pixels). This allows to modify the thickness directly.

float	thickness () const
	Returns the thickness of the lines (in pixels).

Private Member Functions
void	bindSettingsUniform () const

ImplementationType	defaultImplementationType (bool cpuMemPointsProvided) const
	Returns the default supported implementation type that can be used, depending on the capabilities of the current hardware.

bool	setImplementationType (ImplementationType type)

void	updateColorCapability (const std::vector< uint > &vertColors, const std::vector< uint > &lineColors)

void	updateShadingCapability (const std::vector< float > &vertNormals)

Private Attributes
BitSet8	mColorCapability = {false, false, true}

ColorToUse	mColorToUse = ColorToUse::GENERAL

Color	mGeneralColor = Color::ColorABGR::LightGray

std::variant< detail::PrimitiveLines, detail::CPUGeneratedLines >	mLinesImplementation

Uniform	mSettingUH = Uniform("u_settings", bgfx::UniformType::Vec4)

bool	mShadingPerVertex = false

bool	mShadingPerVertexCapability = false

float	mThickness = 5.0f

ImplementationType	mType = ImplementationType::COUNT

Detailed Description

The Lines class provides an abstraction for rendering 3D lines with variable thickness and different implementation strategies.

The Lines class supports several implementation types that are generally determined by the hardware capabilities. Each implementation type has its own advantages and disadvantages in terms of performance and memory usage.

A line can be instantiated using std::vectors or bgfx buffers (VertexBuffer and IndexBuffer). When using std::vectors, the buffers are created and managed internally by the Lines class. When using bgfx buffers, the user is responsible for creating and managing the buffers, and they must remain valid for the lifetime of the Lines object (this is especially valid when the implementation type is PRIMITIVE).

Constructor & Destructor Documentation

◆ Lines() [1/3]

vcl::Lines::Lines ( ImplementationType type = ImplementationType::COUNT )

inline

Creates a Lines object with default parameters and without points.

If the implementation type is not specified, it will be chosen depending on the capabilities of the current hardware.

Parameters

[in] type implementation type to use. If the provided type is not supported by the current hardware, an exception is thrown. If the type is COUNT, the default implementation type will be chosen depending on the capabilities of the current hardware.

◆ Lines() [2/3]

vcl::Lines::Lines	(	const std::vector< float > &	vertCoords,
		const std::vector< float > &	vertNormals,
		const std::vector< uint > &	vertColors,
		const std::vector< uint > &	lineColors,
		float	thickness = `5.0f`,
		bool	shadingPerVertex = `false`,
		ColorToUse	colorToUse = `ColorToUse::GENERAL`,
		ImplementationType	type = `ImplementationType::COUNT`
	)

inline

Creates a Lines object with given points and parameters.

Each line is defined by two consecutive vertices in the vertCoords vector (and related buffers). So the number of lines is equal to vertCoords.size()/6.

If the implementation type is not specified, it will be chosen depending on the capabilities of the current hardware.

Parameters

[in]	vertCoords	vector of vertex coordinates (3 floats per vertex).
[in]	vertNormals	vector of vertex normals (3 floats per vertex), it can be empty.
[in]	vertColors	vector of vertex colors (1 uint per vertex), it can be empty.
[in]	lineColors	vector of line colors (1 uint per line), it can be empty.
[in]	thickness	thickness of the lines (in pixels).
[in]	shadingPerVertex	if true, the lighting is computed using the vertex normals, otherwise no lighting is applied. If this settings is not consistent with the provided buffers, an exception is thrown.
[in]	colorToUse	specifies which color to use for rendering the lines. If this settings is not consistent with the provided buffers, an exception is thrown.
[in]	type	implementation type to use. If the provided type is not supported by the current hardware, an exception is thrown. If the type is COUNT, the default implementation type will be chosen depending on the capabilities of the current hardware.

◆ Lines() [3/3]

vcl::Lines::Lines	(	const std::vector< float > &	vertCoords,
		const std::vector< uint > &	lineIndices,
		const std::vector< float > &	vertNormals,
		const std::vector< uint > &	vertColors,
		const std::vector< uint > &	lineColors,
		float	thickness = `5.0f`,
		bool	shadingPerVertex = `false`,
		ColorToUse	colorToUse = `ColorToUse::GENERAL`,
		ImplementationType	type = `ImplementationType::COUNT`
	)

inline

Creates a Lines object with given points and parameters.

Each line is defined by two consecutive indices in the lineIndices vector, which refer to vertices in the vertCoords vector (and related buffers). So the number of lines is equal to lineIndices.size()/2.

If the implementation type is not specified, it will be chosen depending on the capabilities of the current hardware.

Parameters

[in]	vertCoords	vector of vertex coordinates (3 floats per vertex).
[in]	lineIndices	vector of line indices (2 uint per line).
[in]	vertNormals	vector of vertex normals (3 floats per vertex), it can be empty.
[in]	vertColors	vector of vertex colors (1 uint per vertex), it can be empty.
[in]	lineColors	vector of line colors (1 uint per line), it can be empty.
[in]	thickness	thickness of the lines (in pixels).
[in]	shadingPerVertex	if true, the lighting is computed using the vertex normals, otherwise no lighting is applied. If this settings is not consistent with the provided buffers, an exception is thrown.
[in]	colorToUse	specifies which color to use for rendering the lines. If this settings is not consistent with the provided buffers, an exception is thrown.
[in]	type	implementation type to use. If the provided type is not supported by the current hardware, an exception is thrown. If the type is COUNT, the default implementation type will be chosen depending on the capabilities of the current hardware.

Member Function Documentation

◆ colorToUse()

ColorToUse vcl::Lines::colorToUse ( ) const

inline

Returns the color that is used to render the lines.

Returns: The color that is used to render the lines.

◆ defaultImplementationType()

ImplementationType vcl::Lines::defaultImplementationType ( bool cpuMemPointsProvided ) const

inlineprivate

Returns the default supported implementation type that can be used, depending on the capabilities of the current hardware.

Parameters

[in] cpuMemPointsProvided true if point info of the lines is provided trough CPU memory, false if it is provided through GPU buffers.

Returns: the default supported implementation type

◆ draw()

void vcl::Lines::draw ( uint viewId ) const

inline

Draws in the given view the lines with the current settings.

Parameters

[in] viewId the view in which to draw the lines.

◆ generalColor() [1/2]

Color & vcl::Lines::generalColor ( )

inline

Returns a reference to the general color that is used to render the lines when colorToUse() is set to ColorToUse::GENERAL. This allows to modify the color directly.

Returns: A reference to the general color that is used to render the lines.

◆ generalColor() [2/2]

Color vcl::Lines::generalColor ( ) const

inline

Returns the general color that is used to render the lines when colorToUse() is set to ColorToUse::GENERAL.

Returns: The general color that is used to render the lines.

◆ implementationType()

ImplementationType vcl::Lines::implementationType ( ) const

inline

Returns the current implementation type that is used to render the lines.

Returns: The current implementation type that is used to render the lines.

◆ setColorToUse()

void vcl::Lines::setColorToUse ( ColorToUse color )

inline

Sets which color to use for rendering the lines.

If the provided setting is not consistent with the provided buffers, an exception is thrown.

Parameters

[in] color specifies which color to use for rendering the lines.

◆ setPoints() [1/2]

void vcl::Lines::setPoints	(	const std::vector< float > &	vertCoords,
		const std::vector< float > &	vertNormals,
		const std::vector< uint > &	vertColors,
		const std::vector< uint > &	lineColors,
		ImplementationType	type = `ImplementationType::COUNT`
	)

inline

Sets the points of the lines.

Each line is defined by two consecutive vertices in the vertCoords vector (and related buffers). So the number of lines is equal to vertCoords.size()/6.

If the implementation type is not specified, it will be chosen depending on the capabilities of the current hardware.

Parameters

[in]	vertCoords	vector of vertex coordinates (3 floats per vertex).
[in]	vertNormals	vector of vertex normals (3 floats per vertex), it can be empty.
[in]	vertColors	vector of vertex colors (1 uint per vertex), it can be empty.
[in]	lineColors	vector of line colors (1 uint per line), it can be empty.
[in]	type	implementation type to use. If the provided type is not supported by the current hardware, an exception is thrown. If the type is COUNT, the default implementation type will be chosen depending on the capabilities of the current hardware.

◆ setPoints() [2/2]

void vcl::Lines::setPoints	(	const std::vector< float > &	vertCoords,
		const std::vector< uint > &	lineIndices,
		const std::vector< float > &	vertNormals,
		const std::vector< uint > &	vertColors,
		const std::vector< uint > &	lineColors,
		ImplementationType	type = `ImplementationType::COUNT`
	)

inline

Sets the points of the lines.

Each line is defined by two consecutive indices in the lineIndices vector, which refer to vertices in the vertCoords vector (and related buffers). So the number of lines is equal to lineIndices.size()/2.

If the implementation type is not specified, it will be chosen depending on the capabilities of the current hardware.

Parameters

[in]	vertCoords	vector of vertex coordinates (3 floats per vertex).
[in]	lineIndices	vector of line indices (2 uint per line).
[in]	vertNormals	vector of vertex normals (3 floats per vertex), it can be empty.
[in]	vertColors	vector of vertex colors (1 uint per vertex), it can be empty.
[in]	lineColors	vector of line colors (1 uint per line), it can be empty.
[in]	type	implementation type to use. If the provided type is not supported by the current hardware, an exception is thrown. If the type is COUNT, the default implementation type will be chosen depending on the capabilities of the current hardware.

◆ setShading()

void vcl::Lines::setShading ( bool perVertex )

inline

Sets wether to use per vertex shading (using vertex normals) or not.

If the provided setting is not consistent with the provided buffers, an exception is thrown.

Parameters

[in] perVertex if true, the lighting is computed using the vertex normals, otherwise no lighting is applied. If this settings

◆ shadingPerVertex()

bool vcl::Lines::shadingPerVertex ( ) const

inline

Returns true if shading is computed per vertex using vertex normals, false if no shading is applied.

Returns: true if shading is computed per vertex using vertex normals.

◆ thickness() [1/2]

float & vcl::Lines::thickness ( )

inline

Returns a reference to the thickness of the lines (in pixels). This allows to modify the thickness directly.

Returns: A reference to the thickness of the lines (in pixels).

◆ thickness() [2/2]

float vcl::Lines::thickness ( ) const

inline

Returns the thickness of the lines (in pixels).

Returns: The thickness of the lines (in pixels).

The documentation for this class was generated from the following file:

vclib/render/include/vclib/bgfx/primitives/lines.h

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Lines() [1/3]

◆ Lines() [2/3]

◆ Lines() [3/3]

Member Function Documentation

◆ colorToUse()

◆ defaultImplementationType()

◆ draw()

◆ generalColor() [1/2]

◆ generalColor() [2/2]

◆ implementationType()

◆ setColorToUse()

◆ setPoints() [1/2]

◆ setPoints() [2/2]

◆ setShading()

◆ shadingPerVertex()

◆ thickness() [1/2]

◆ thickness() [2/2]