MRLaplacian.h File Reference

#include <MRCMesh/MREnums.h>
#include <MRCMesh/MRId.h>
#include <MRCMesh/MRVector3.h>
#include <MRCMisc/common.h>
#include <MRCMisc/exports.h>
#include <stdbool.h>
#include <stddef.h>

Go to the source code of this file.

Typedefs
typedef struct MR_Laplacian_Attractor	MR_Laplacian_Attractor
typedef struct MR_Laplacian	MR_Laplacian

Functions
MRC_API MR_Laplacian *	MR_Laplacian_ConstructFromAnother (MR_PassBy _other_pass_by, MR_Laplacian *_other)
MRC_API const MR_Laplacian *	MR_Laplacian_OffsetPtr (const MR_Laplacian *ptr, ptrdiff_t i)
MRC_API MR_Laplacian *	MR_Laplacian_OffsetMutablePtr (MR_Laplacian *ptr, ptrdiff_t i)
MRC_API MR_Laplacian *	MR_Laplacian_Construct_1 (MR_Mesh *mesh)
MRC_API MR_Laplacian *	MR_Laplacian_Construct_2 (const MR_MeshTopology *topology, MR_VertCoords *points)
MRC_API void	MR_Laplacian_Destroy (const MR_Laplacian *_this)
	Destroys a heap-allocated instance of MR_Laplacian. Does nothing if the pointer is null.
MRC_API void	MR_Laplacian_DestroyArray (const MR_Laplacian *_this)
	Destroys a heap-allocated array of MR_Laplacian. Does nothing if the pointer is null.
MRC_API void	MR_Laplacian_init (MR_Laplacian *_this, const MR_VertBitSet *freeVerts, MR_EdgeWeights weights, const MR_VertexMass *vmass, const MR_RememberShape *rem)
MRC_API void	MR_Laplacian_initFromPoints (MR_Laplacian *_this, const MR_VertCoords *points, const MR_VertBitSet *freeVerts, MR_EdgeWeights weights, const MR_VertexMass *vmass, const MR_RememberShape *rem)
MRC_API void	MR_Laplacian_fixVertex_2 (MR_Laplacian *_this, MR_VertId v, const bool *smooth)
MRC_API void	MR_Laplacian_fixVertex_3 (MR_Laplacian *_this, MR_VertId v, const MR_Vector3f *fixedPos, const bool *smooth)
MRC_API void	MR_Laplacian_multVertexWeight (MR_Laplacian *_this, MR_VertId v, double factor)
MRC_API void	MR_Laplacian_updateSolver (MR_Laplacian *_this)
MRC_API void	MR_Laplacian_applyToVector (MR_Laplacian *_this, MR_VertCoords *points)
MRC_API void	MR_Laplacian_apply (MR_Laplacian *_this)
MRC_API void	MR_Laplacian_applyToScalar (MR_Laplacian *_this, MR_VertScalars *scalarField)
MRC_API const MR_VertBitSet *	MR_Laplacian_region (const MR_Laplacian *_this)
MRC_API const MR_VertBitSet *	MR_Laplacian_freeVerts (const MR_Laplacian *_this)
MRC_API const MR_VertBitSet *	MR_Laplacian_firstLayerFixedVerts (const MR_Laplacian *_this)
MRC_API const MR_MeshTopology *	MR_Laplacian_topology (const MR_Laplacian *_this)
MRC_API MR_VertCoords *	MR_Laplacian_points (const MR_Laplacian *_this)
MRC_API void	MR_Laplacian_addAttractor (MR_Laplacian *_this, const MR_Laplacian_Attractor *a)
MRC_API void	MR_Laplacian_removeAllAttractors (MR_Laplacian *_this)
MRC_API const MR_MeshTriPoint *	MR_Laplacian_Attractor_Get_p (const MR_Laplacian_Attractor *_this)
MRC_API void	MR_Laplacian_Attractor_Set_p (MR_Laplacian_Attractor *_this, const MR_MeshTriPoint *value)
MRC_API MR_MeshTriPoint *	MR_Laplacian_Attractor_GetMutable_p (MR_Laplacian_Attractor *_this)
MRC_API const MR_Vector3d *	MR_Laplacian_Attractor_Get_target (const MR_Laplacian_Attractor *_this)
MRC_API void	MR_Laplacian_Attractor_Set_target (MR_Laplacian_Attractor *_this, MR_Vector3d value)
MRC_API MR_Vector3d *	MR_Laplacian_Attractor_GetMutable_target (MR_Laplacian_Attractor *_this)
MRC_API const double *	MR_Laplacian_Attractor_Get_weight (const MR_Laplacian_Attractor *_this)
MRC_API void	MR_Laplacian_Attractor_Set_weight (MR_Laplacian_Attractor *_this, double value)
MRC_API double *	MR_Laplacian_Attractor_GetMutable_weight (MR_Laplacian_Attractor *_this)
MRC_API MR_Laplacian_Attractor *	MR_Laplacian_Attractor_DefaultConstruct (void)
MRC_API MR_Laplacian_Attractor *	MR_Laplacian_Attractor_DefaultConstructArray (size_t num_elems)
MRC_API MR_Laplacian_Attractor *	MR_Laplacian_Attractor_ConstructFrom (const MR_MeshTriPoint *p, MR_Vector3d target, double weight)
MRC_API const MR_Laplacian_Attractor *	MR_Laplacian_Attractor_OffsetPtr (const MR_Laplacian_Attractor *ptr, ptrdiff_t i)
MRC_API MR_Laplacian_Attractor *	MR_Laplacian_Attractor_OffsetMutablePtr (MR_Laplacian_Attractor *ptr, ptrdiff_t i)
MRC_API MR_Laplacian_Attractor *	MR_Laplacian_Attractor_ConstructFromAnother (const MR_Laplacian_Attractor *_other)
MRC_API void	MR_Laplacian_Attractor_Destroy (const MR_Laplacian_Attractor *_this)
	Destroys a heap-allocated instance of MR_Laplacian_Attractor. Does nothing if the pointer is null.
MRC_API void	MR_Laplacian_Attractor_DestroyArray (const MR_Laplacian_Attractor *_this)
	Destroys a heap-allocated array of MR_Laplacian_Attractor. Does nothing if the pointer is null.
MRC_API MR_Laplacian_Attractor *	MR_Laplacian_Attractor_AssignFromAnother (MR_Laplacian_Attractor *_this, const MR_Laplacian_Attractor *_other)

Typedef Documentation

MR_Laplacian

typedef struct MR_Laplacian MR_Laplacian

Laplacian to smoothly deform a region preserving mesh fine details. How to use:

1. Initialize Laplacian for the region being deformed, here region properties are remembered.
2. Change positions of some vertices within the region and call fixVertex for them.
3. Optionally call updateSolver()
4. Call apply() to change the remaining vertices within the region Then steps 1-4 or 2-4 can be repeated.
   Generated from class MR::Laplacian. Supported MR_PassBy modes: MR_PassBy_Move (and MR_PassBy_DefaultArgument and MR_PassBy_NoObject if supported by the callee).

MR_Laplacian_Attractor

typedef struct MR_Laplacian_Attractor MR_Laplacian_Attractor

attracts the given point inside some mesh's triangle to the given target with the given weight Generated from class MR::Laplacian::Attractor. Supported MR_PassBy modes: MR_PassBy_DefaultConstruct, MR_PassBy_Copy, MR_PassBy_Move (and MR_PassBy_DefaultArgument and MR_PassBy_NoObject if supported by the callee).

Function Documentation

MR_Laplacian_addAttractor()

MRC_API void MR_Laplacian_addAttractor	(	MR_Laplacian *	_this,
		const MR_Laplacian_Attractor *	a )

adds one more attractor to the stored list Generated from method MR::Laplacian::addAttractor. Parameter _this can not be null. It is a single object. Parameter a can not be null. It is a single object.

MR_Laplacian_apply()

MRC_API void MR_Laplacian_apply

(

MR_Laplacian *

_this

)

takes fixed vertex positions from the points vector passed to a constructor, computes and writes free vertex positions in the points vector passed to a constructor as well Generated from method MR::Laplacian::apply. Parameter _this can not be null. It is a single object.

MR_Laplacian_applyToScalar()

MRC_API void MR_Laplacian_applyToScalar	(	MR_Laplacian *	_this,
		MR_VertScalars *	scalarField )

takes fixed vertex scalars from the given field, computes and writes free vertex scalars in the given field as well Generated from method MR::Laplacian::applyToScalar. Parameter _this can not be null. It is a single object. Parameter scalarField can not be null. It is a single object.

MR_Laplacian_applyToVector()

MRC_API void MR_Laplacian_applyToVector	(	MR_Laplacian *	_this,
		MR_VertCoords *	points )

takes fixed vertex positions from the given points vector, computes and writes free vertex positions in the given points vector as well Generated from method MR::Laplacian::applyToVector. Parameter _this can not be null. It is a single object. Parameter points can not be null. It is a single object.

MR_Laplacian_Attractor_AssignFromAnother()

MRC_API MR_Laplacian_Attractor * MR_Laplacian_Attractor_AssignFromAnother	(	MR_Laplacian_Attractor *	_this,
		const MR_Laplacian_Attractor *	_other )

Generated from method MR::Laplacian::Attractor::operator=. Parameter _this can not be null. It is a single object. Parameter _other can not be null. It is a single object. The reference to things referred to by the parameter _other (if any) might be preserved in this object. The returned pointer will never be null. It is non-owning, do NOT destroy it. When this function is called, this object will drop any object references it held previously.

MR_Laplacian_Attractor_ConstructFrom()

MRC_API MR_Laplacian_Attractor * MR_Laplacian_Attractor_ConstructFrom	(	const MR_MeshTriPoint *	p,
		MR_Vector3d	target,
		double	weight )

Constructs MR::Laplacian::Attractor elementwise. Parameter p can not be null. It is a single object. The reference to the parameter p might be preserved in the constructed object. The reference to the parameter target might be preserved in the constructed object. Never returns null. Returns an instance allocated on the heap! Must call MR_Laplacian_Attractor_Destroy() to free it when you're done using it. When this function is called, this object will drop any object references it held previously.

MR_Laplacian_Attractor_ConstructFromAnother()

MRC_API MR_Laplacian_Attractor * MR_Laplacian_Attractor_ConstructFromAnother

(

const MR_Laplacian_Attractor *

_other

)

Generated from constructor MR::Laplacian::Attractor::Attractor. Parameter _other can not be null. It is a single object. The reference to things referred to by the parameter _other (if any) might be preserved in the constructed object. Never returns null. Returns an instance allocated on the heap! Must call MR_Laplacian_Attractor_Destroy() to free it when you're done using it.

MR_Laplacian_Attractor_DefaultConstruct()

MRC_API MR_Laplacian_Attractor * MR_Laplacian_Attractor_DefaultConstruct

(

void

)

Constructs an empty (default-constructed) instance. Never returns null. Returns an instance allocated on the heap! Must call MR_Laplacian_Attractor_Destroy() to free it when you're done using it.

MR_Laplacian_Attractor_DefaultConstructArray()

MRC_API MR_Laplacian_Attractor * MR_Laplacian_Attractor_DefaultConstructArray

(

size_t

num_elems

)

Constructs an array of empty (default-constructed) instances, of the specified size. Will never return null. The array must be destroyed using MR_Laplacian_Attractor_DestroyArray(). Use MR_Laplacian_Attractor_OffsetMutablePtr() and MR_Laplacian_Attractor_OffsetPtr() to access the array elements.

MR_Laplacian_Attractor_Destroy()

MRC_API void MR_Laplacian_Attractor_Destroy

(

const MR_Laplacian_Attractor *

_this

)

Destroys a heap-allocated instance of MR_Laplacian_Attractor. Does nothing if the pointer is null.

MR_Laplacian_Attractor_DestroyArray()

MRC_API void MR_Laplacian_Attractor_DestroyArray

(

const MR_Laplacian_Attractor *

_this

)

Destroys a heap-allocated array of MR_Laplacian_Attractor. Does nothing if the pointer is null.

MR_Laplacian_Attractor_Get_p()

MRC_API const MR_MeshTriPoint * MR_Laplacian_Attractor_Get_p

(

const MR_Laplacian_Attractor *

_this

)

Returns a pointer to a member variable of class MR::Laplacian::Attractor named p. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it. The reference to this object might be preserved as the return value.

MR_Laplacian_Attractor_Get_target()

MRC_API const MR_Vector3d * MR_Laplacian_Attractor_Get_target

(

const MR_Laplacian_Attractor *

_this

)

Returns a pointer to a member variable of class MR::Laplacian::Attractor named target. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it. The reference to this object might be preserved as the return value.

MR_Laplacian_Attractor_Get_weight()

MRC_API const double * MR_Laplacian_Attractor_Get_weight

(

const MR_Laplacian_Attractor *

_this

)

the weight or priority of this attractor relative to all other equations, which must be compatible with weights of other equations; the weight of ordinary equations is 1 for VertexMass::Unit, and 1 / sqrt( double area around central vertex ) for VertexMass::NeiArea Returns a pointer to a member variable of class MR::Laplacian::Attractor named weight. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it. The reference to this object might be preserved as the return value.

MR_Laplacian_Attractor_GetMutable_p()

MRC_API MR_MeshTriPoint * MR_Laplacian_Attractor_GetMutable_p

(

MR_Laplacian_Attractor *

_this

)

Returns a mutable pointer to a member variable of class MR::Laplacian::Attractor named p. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it. The reference to this object might be preserved as the return value.

MR_Laplacian_Attractor_GetMutable_target()

MRC_API MR_Vector3d * MR_Laplacian_Attractor_GetMutable_target

(

MR_Laplacian_Attractor *

_this

)

Returns a mutable pointer to a member variable of class MR::Laplacian::Attractor named target. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it. The reference to this object might be preserved as the return value.

MR_Laplacian_Attractor_GetMutable_weight()

MRC_API double * MR_Laplacian_Attractor_GetMutable_weight

(

MR_Laplacian_Attractor *

_this

)

the weight or priority of this attractor relative to all other equations, which must be compatible with weights of other equations; the weight of ordinary equations is 1 for VertexMass::Unit, and 1 / sqrt( double area around central vertex ) for VertexMass::NeiArea Returns a mutable pointer to a member variable of class MR::Laplacian::Attractor named weight. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it. The reference to this object might be preserved as the return value.

MR_Laplacian_Attractor_OffsetMutablePtr()

MRC_API MR_Laplacian_Attractor * MR_Laplacian_Attractor_OffsetMutablePtr	(	MR_Laplacian_Attractor *	ptr,
		ptrdiff_t	i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element. The reference to the parameter ptr might be preserved in the return value.

MR_Laplacian_Attractor_OffsetPtr()

MRC_API const MR_Laplacian_Attractor * MR_Laplacian_Attractor_OffsetPtr	(	const MR_Laplacian_Attractor *	ptr,
		ptrdiff_t	i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element. The reference to the parameter ptr might be preserved in the return value.

MR_Laplacian_Attractor_Set_p()

MRC_API void MR_Laplacian_Attractor_Set_p	(	MR_Laplacian_Attractor *	_this,
		const MR_MeshTriPoint *	value )

Modifies a member variable of class MR::Laplacian::Attractor named p. Parameter _this can not be null. It is a single object. Parameter value can not be null. It is a single object. The reference to the parameter value might be preserved in this object in element p. When this function is called, this object will drop object references it held previously in p.

MR_Laplacian_Attractor_Set_target()

MRC_API void MR_Laplacian_Attractor_Set_target	(	MR_Laplacian_Attractor *	_this,
		MR_Vector3d	value )

Modifies a member variable of class MR::Laplacian::Attractor named target. Parameter _this can not be null. It is a single object. The reference to the parameter value might be preserved in this object in element target. When this function is called, this object will drop object references it held previously in target.

MR_Laplacian_Attractor_Set_weight()

MRC_API void MR_Laplacian_Attractor_Set_weight	(	MR_Laplacian_Attractor *	_this,
		double	value )

the weight or priority of this attractor relative to all other equations, which must be compatible with weights of other equations; the weight of ordinary equations is 1 for VertexMass::Unit, and 1 / sqrt( double area around central vertex ) for VertexMass::NeiArea Modifies a member variable of class MR::Laplacian::Attractor named weight. Parameter _this can not be null. It is a single object. When this function is called, this object will drop object references it held previously in weight.

MR_Laplacian_Construct_1()

MRC_API MR_Laplacian * MR_Laplacian_Construct_1

(

MR_Mesh *

mesh

)

Generated from constructor MR::Laplacian::Laplacian. Parameter mesh can not be null. It is a single object. The reference to the parameter mesh might be preserved in the constructed object. Never returns null. Returns an instance allocated on the heap! Must call MR_Laplacian_Destroy() to free it when you're done using it.

MR_Laplacian_Construct_2()

MRC_API MR_Laplacian * MR_Laplacian_Construct_2	(	const MR_MeshTopology *	topology,
		MR_VertCoords *	points )

Generated from constructor MR::Laplacian::Laplacian. Parameter topology can not be null. It is a single object. The reference to the parameter topology might be preserved in the constructed object. Parameter points can not be null. It is a single object. The reference to the parameter points might be preserved in the constructed object. Never returns null. Returns an instance allocated on the heap! Must call MR_Laplacian_Destroy() to free it when you're done using it.

MR_Laplacian_ConstructFromAnother()

MRC_API MR_Laplacian * MR_Laplacian_ConstructFromAnother	(	MR_PassBy	_other_pass_by,
		MR_Laplacian *	_other )

Generated from constructor MR::Laplacian::Laplacian. The reference to things referred to by the parameter _other (if any) might be preserved in the constructed object. Never returns null. Returns an instance allocated on the heap! Must call MR_Laplacian_Destroy() to free it when you're done using it.

MR_Laplacian_Destroy()

MRC_API void MR_Laplacian_Destroy

(

const MR_Laplacian *

_this

)

Destroys a heap-allocated instance of MR_Laplacian. Does nothing if the pointer is null.

MR_Laplacian_DestroyArray()

MRC_API void MR_Laplacian_DestroyArray

(

const MR_Laplacian *

_this

)

Destroys a heap-allocated array of MR_Laplacian. Does nothing if the pointer is null.

MR_Laplacian_firstLayerFixedVerts()

MRC_API const MR_VertBitSet * MR_Laplacian_firstLayerFixedVerts

(

const MR_Laplacian *

_this

)

return fixed vertices from the first layer around free vertices Generated from method MR::Laplacian::firstLayerFixedVerts. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

MR_Laplacian_fixVertex_2()

MRC_API void MR_Laplacian_fixVertex_2	(	MR_Laplacian *	_this,
		MR_VertId	v,
		const bool *	smooth )

notify Laplacian that given vertex has changed after init and must be fixed during apply;

Parameters

smooth

whether to make the surface smooth in this vertex (sharp otherwise) Generated from method MR::Laplacian::fixVertex. Parameter _this can not be null. It is a single object. Parameter smooth has a default argument: true, pass a null pointer to use it.

MR_Laplacian_fixVertex_3()

MRC_API void MR_Laplacian_fixVertex_3	(	MR_Laplacian *	_this,
		MR_VertId	v,
		const MR_Vector3f *	fixedPos,
		const bool *	smooth )

sets position of given vertex after init and it must be fixed during apply (THIS METHOD CHANGES THE MESH);

Parameters

smooth

whether to make the surface smooth in this vertex (sharp otherwise) Generated from method MR::Laplacian::fixVertex. Parameter _this can not be null. It is a single object. Parameter fixedPos can not be null. It is a single object. Parameter smooth has a default argument: true, pass a null pointer to use it.

MR_Laplacian_freeVerts()

MRC_API const MR_VertBitSet * MR_Laplacian_freeVerts

(

const MR_Laplacian *

_this

)

return currently free vertices Generated from method MR::Laplacian::freeVerts. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

MR_Laplacian_init()

MRC_API void MR_Laplacian_init	(	MR_Laplacian *	_this,
		const MR_VertBitSet *	freeVerts,
		MR_EdgeWeights	weights,
		const MR_VertexMass *	vmass,
		const MR_RememberShape *	rem )

(re)initialize Laplacian for the region being deformed, here region properties are remembered and precomputed;

Parameters

freeVerts

must not include all vertices of a mesh connected component;

usePoints

is not nullptr, then these points will be used instead of passed to a constructor for weights computation and shape memory Generated from method MR::Laplacian::init. Parameter _this can not be null. It is a single object. Parameter freeVerts can not be null. It is a single object. Parameter vmass has a default argument: VertexMass::Unit, pass a null pointer to use it. Parameter rem has a default argument: RememberShape::Yes, pass a null pointer to use it.

MR_Laplacian_initFromPoints()

MRC_API void MR_Laplacian_initFromPoints	(	MR_Laplacian *	_this,
		const MR_VertCoords *	points,
		const MR_VertBitSet *	freeVerts,
		MR_EdgeWeights	weights,
		const MR_VertexMass *	vmass,
		const MR_RememberShape *	rem )

same as init() but uses the given points instead of ones passed to a constructor for weights computation and shape memory Generated from method MR::Laplacian::initFromPoints. Parameter _this can not be null. It is a single object. Parameter points can not be null. It is a single object. Parameter freeVerts can not be null. It is a single object. Parameter vmass has a default argument: VertexMass::Unit, pass a null pointer to use it. Parameter rem has a default argument: RememberShape::Yes, pass a null pointer to use it.

MR_Laplacian_multVertexWeight()

MRC_API void MR_Laplacian_multVertexWeight	(	MR_Laplacian *	_this,
		MR_VertId	v,
		double	factor )

multiplies vertex equation's weight on the given factor Generated from method MR::Laplacian::multVertexWeight. Parameter _this can not be null. It is a single object.

MR_Laplacian_OffsetMutablePtr()

MRC_API MR_Laplacian * MR_Laplacian_OffsetMutablePtr	(	MR_Laplacian *	ptr,
		ptrdiff_t	i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element. The reference to the parameter ptr might be preserved in the return value.

MR_Laplacian_OffsetPtr()

MRC_API const MR_Laplacian * MR_Laplacian_OffsetPtr	(	const MR_Laplacian *	ptr,
		ptrdiff_t	i )

Offsets a pointer to an array element by i positions (not bytes). Use only if you're certain that the pointer points to an array element. The reference to the parameter ptr might be preserved in the return value.

MR_Laplacian_points()

MRC_API MR_VertCoords * MR_Laplacian_points

(

const MR_Laplacian *

_this

)

return the vector of coordinates for which Laplacian was constructed Generated from method MR::Laplacian::points. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

MR_Laplacian_region()

MRC_API const MR_VertBitSet * MR_Laplacian_region

(

const MR_Laplacian *

_this

)

return all initially free vertices and the first layer of vertices around them Generated from method MR::Laplacian::region. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

MR_Laplacian_removeAllAttractors()

MRC_API void MR_Laplacian_removeAllAttractors

(

MR_Laplacian *

_this

)

forgets all attractors added previously Generated from method MR::Laplacian::removeAllAttractors. Parameter _this can not be null. It is a single object.

MR_Laplacian_topology()

MRC_API const MR_MeshTopology * MR_Laplacian_topology

(

const MR_Laplacian *

_this

)

return the topology for which Laplacian was constructed Generated from method MR::Laplacian::topology. Parameter _this can not be null. It is a single object. The returned pointer will never be null. It is non-owning, do NOT destroy it.

MR_Laplacian_updateSolver()

MRC_API void MR_Laplacian_updateSolver

(

MR_Laplacian *

_this

)

if you manually call this method after initialization and fixing vertices then next apply call will be much faster Generated from method MR::Laplacian::updateSolver. Parameter _this can not be null. It is a single object.