/src/ogre/OgreMain/include/OgreOptimisedUtil.h

Source
/*
-----------------------------------------------------------------------------
This source file is part of OGRE
    (Object-oriented Graphics Rendering Engine)
For the latest info, see http://www.ogre3d.org/

Copyright (c) 2000-2014 Torus Knot Software Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
-----------------------------------------------------------------------------
*/
#ifndef __OptimisedUtil_H__
#define __OptimisedUtil_H__

#include "OgrePrerequisites.h"
#include "OgreEdgeListBuilder.h"
#include <cstddef>

namespace Ogre {

    /** \addtogroup Core
    *  @{
    */
    /** \addtogroup Math
    *  @{
    */
    /** Utility class for provides optimised functions.
    @note
        This class are supposed used by internal engine only.
    */
    class _OgreExport OptimisedUtil
    {
    private:
        /// Privated copy constructor, to prevent misuse
        OptimisedUtil(const OptimisedUtil& rhs); /* do nothing, should not use */
        /// Privated operator=, to prevent misuse
        OptimisedUtil& operator=(const OptimisedUtil& rhs); /* do not use */

    protected:
        /// Store a pointer to the implementation
        static OptimisedUtil* msImplementation;

        /// Detect best implementation based on run-time environment
        static OptimisedUtil* _detectImplementation(void);

    public:
        // Default constructor
        OptimisedUtil(void) {}
        // Destructor
        virtual ~OptimisedUtil() {}

        /** Gets the implementation of this class.
        @note
            Don't cache the pointer returned by this function, it'll change due
            run-time environment detection to pick up the best implementation.
        */
        static OptimisedUtil* getImplementation(void) { return msImplementation; }

        /** Performs software vertex skinning.
        @param srcPosPtr Pointer to source position buffer.
        @param destPosPtr Pointer to destination position buffer.
        @param srcNormPtr Pointer to source normal buffer, if NULL,
            means blend position only.
        @param destNormPtr Pointer to destination normal buffer, it's
            ignored if srcNormPtr is NULL.
        @param blendWeightPtr Pointer to blend weight buffer.
        @param blendIndexPtr Pointer to blend index buffer.
        @param blendMatrices An array of pointer of blend matrix, the matrix
            must be aligned to SIMD alignment, but not necessary for the array
            itself.
        @param srcPosStride The stride of source position in bytes.
        @param destPosStride The stride of destination position in bytes.
        @param srcNormStride The stride of source normal in bytes,
            it's ignored if srcNormPtr is NULL.
        @param destNormStride The stride of destination normal in bytes,
            it's ignored if srcNormPtr is NULL.
        @param blendWeightStride The stride of blend weight buffer in bytes.
        @param blendIndexStride The stride of blend index buffer in bytes.
        @param numWeightsPerVertex Number of blend weights per-vertex, as well
            as for blend indices.
        @param numVertices Number of vertices to blend.
        */
        virtual void softwareVertexSkinning(
            const float *srcPosPtr, float *destPosPtr,
            const float *srcNormPtr, float *destNormPtr,
            const float *blendWeightPtr, const unsigned char* blendIndexPtr,
            const Affine3* const* blendMatrices,
            size_t srcPosStride, size_t destPosStride,
            size_t srcNormStride, size_t destNormStride,
            size_t blendWeightStride, size_t blendIndexStride,
            size_t numWeightsPerVertex,
            size_t numVertices) = 0;

        /** Performs a software vertex morph, of the kind used for
            morph animation although it can be used for other purposes. 

            This function will linearly interpolate positions between two
            source buffers, into a third buffer.
        @param t Parametric distance between the start and end positions
        @param srcPos1 Pointer to buffer for the start positions
        @param srcPos2 Pointer to buffer for the end positions
        @param dstPos Pointer to buffer for the destination positions
        @param pos1VSize, pos2VSize, dstVSize Vertex sizes in bytes of each of the 3 buffers referenced
        @param numVertices Number of vertices to morph, which agree with
            the number in start, end and destination buffer. Bear in mind
            three floating-point values per vertex
        @param morphNormals
        */
        virtual void softwareVertexMorph(
            float t,
            const float *srcPos1, const float *srcPos2,
            float *dstPos,
            size_t pos1VSize, size_t pos2VSize, size_t dstVSize, 
            size_t numVertices,
            bool morphNormals) = 0;

        /** Concatenate an affine matrix to an array of affine matrices.
        @note
            An affine matrix is a 4x4 matrix with row 3 equal to (0, 0, 0, 1),
            e.g. no projective coefficients.
        @param baseMatrix The matrix used as first operand.
        @param srcMatrices An array of matrix used as second operand.
        @param dstMatrices An array of matrix to store matrix concatenate results.
        @param numMatrices Number of matrices in the array.
        */
        virtual void concatenateAffineMatrices(
            const Affine3& baseMatrix,
            const Affine3* srcMatrices,
            Affine3* dstMatrices,
            size_t numMatrices) = 0;

        /** Calculate the face normals for the triangles based on position
            information.
        @param positions Pointer to position information, which packed in
            (x, y, z) format, indexing by vertex index in the triangle. No
            alignment requests.
        @param triangles The triangles need to calculate face normal, the vertex
            positions is indexed by vertex index to position information.
        @param faceNormals The array of Vector4 used to store triangles face normal,
            Must be aligned to SIMD alignment.
        @param numTriangles Number of triangles to calculate face normal.
        */
        virtual void calculateFaceNormals(
            const float *positions,
            const EdgeData::Triangle *triangles,
            Vector4 *faceNormals,
            size_t numTriangles) = 0;

        /** Calculate the light facing state of the triangle's face normals

            This is normally the first stage of calculating a silhouette, i.e.
            establishing which tris are facing the light and which are facing
            away.
        @param lightPos 4D position of the light in object space, note that
            for directional lights (which have no position), the w component
            is 0 and the x/y/z position are the direction.
        @param faceNormals An array of face normals for the triangles, the face
            normal are unit vector orthogonal to the triangles, plus distance
            from origin. This array must be aligned to SIMD alignment.
        @param lightFacings An array of flags for store light facing state
            results, the result flag is true if corresponding face normal facing
            the light, false otherwise. This array no alignment requires.
        @param numFaces Number of face normals to calculate.
        */
        virtual void calculateLightFacing(
            const Vector4& lightPos,
            const Vector4* faceNormals,
            char* lightFacings,
            size_t numFaces) = 0;

        /** Extruding vertices by a fixed distance based on light position.
        @param lightPos 4D light position, when w=0.0f this represents a
            directional light, otherwise, w must be equal to 1.0f, which
            represents a point light.
        @param extrudeDist The distance to extrude.
        @param srcPositions Pointer to source vertex's position buffer, which
            the position is a 3D vector packed in xyz format. No SIMD alignment
            requirement but loss performance for unaligned data.
        @param destPositions Pointer to destination vertex's position buffer,
            which the position is a 3D vector packed in xyz format. No SIMD
            alignment requirement but loss performance for unaligned data.
        @param numVertices Number of vertices need to extruding, which agree
            with source and destination buffers.
        */
        virtual void extrudeVertices(
            const Vector4& lightPos,
            Real extrudeDist,
            const float* srcPositions,
            float* destPositions,
            size_t numVertices) = 0;
    };

    /** Returns raw offsetted of the given pointer.
    @note
        The offset are in bytes, no matter what type of the pointer.
    */
    template <class T>
    static OGRE_FORCE_INLINE const T* rawOffsetPointer(const T* ptr, ptrdiff_t offset)
    {
        return (const T*)((const char*)(ptr) + offset);
    }

    template <class T>
    static OGRE_FORCE_INLINE T* rawOffsetPointer(T* ptr, ptrdiff_t offset)
    {
        return (T*)((char*)(ptr) + offset);
    }

    /** Advance the pointer with raw offset.
    @note
        The offset are in bytes, no matter what type of the pointer.
    */
    template <class T>
    static OGRE_FORCE_INLINE void advanceRawPointer(const T*& ptr, ptrdiff_t offset)
    {
        ptr = rawOffsetPointer(ptr, offset);
    }

    template <class T>
    static OGRE_FORCE_INLINE void advanceRawPointer(T*& ptr, ptrdiff_t offset)
    {
        ptr = rawOffsetPointer(ptr, offset);
    }
    /** @} */
    /** @} */

}

#endif  // __OptimisedUtil_H__

Coverage Report

Created: 2025-10-10 06:46

Line	Count	Source
1		/*
2		-----------------------------------------------------------------------------
3		This source file is part of OGRE
4		(Object-oriented Graphics Rendering Engine)
5		For the latest info, see http://www.ogre3d.org/
6
7		Copyright (c) 2000-2014 Torus Knot Software Ltd
8
9		Permission is hereby granted, free of charge, to any person obtaining a copy
10		of this software and associated documentation files (the "Software"), to deal
11		in the Software without restriction, including without limitation the rights
12		to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13		copies of the Software, and to permit persons to whom the Software is
14		furnished to do so, subject to the following conditions:
15
16		The above copyright notice and this permission notice shall be included in
17		all copies or substantial portions of the Software.
18
19		THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20		IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21		FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22		AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23		LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24		OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25		THE SOFTWARE.
26		-----------------------------------------------------------------------------
27		*/
28		#ifndef __OptimisedUtil_H__
29		#define __OptimisedUtil_H__
30
31		#include "OgrePrerequisites.h"
32		#include "OgreEdgeListBuilder.h"
33		#include <cstddef>
34
35		namespace Ogre {
36
37		/** \addtogroup Core
38		* @{
39		*/
40		/** \addtogroup Math
41		* @{
42		*/
43		/** Utility class for provides optimised functions.
44		@note
45		This class are supposed used by internal engine only.
46		*/
47		class _OgreExport OptimisedUtil
48		{
49		private:
50		/// Privated copy constructor, to prevent misuse
51		OptimisedUtil(const OptimisedUtil& rhs); /* do nothing, should not use */
52		/// Privated operator=, to prevent misuse
53		OptimisedUtil& operator=(const OptimisedUtil& rhs); /* do not use */
54
55		protected:
56		/// Store a pointer to the implementation
57		static OptimisedUtil* msImplementation;
58
59		/// Detect best implementation based on run-time environment
60		static OptimisedUtil* _detectImplementation(void);
61
62		public:
63		// Default constructor
64	4	OptimisedUtil(void) {}
65		// Destructor
66	0	virtual ~OptimisedUtil() {}
67
68		/** Gets the implementation of this class.
69		@note
70		Don't cache the pointer returned by this function, it'll change due
71		run-time environment detection to pick up the best implementation.
72		*/
73	0	static OptimisedUtil* getImplementation(void) { return msImplementation; }
74
75		/** Performs software vertex skinning.
76		@param srcPosPtr Pointer to source position buffer.
77		@param destPosPtr Pointer to destination position buffer.
78		@param srcNormPtr Pointer to source normal buffer, if NULL,
79		means blend position only.
80		@param destNormPtr Pointer to destination normal buffer, it's
81		ignored if srcNormPtr is NULL.
82		@param blendWeightPtr Pointer to blend weight buffer.
83		@param blendIndexPtr Pointer to blend index buffer.
84		@param blendMatrices An array of pointer of blend matrix, the matrix
85		must be aligned to SIMD alignment, but not necessary for the array
86		itself.
87		@param srcPosStride The stride of source position in bytes.
88		@param destPosStride The stride of destination position in bytes.
89		@param srcNormStride The stride of source normal in bytes,
90		it's ignored if srcNormPtr is NULL.
91		@param destNormStride The stride of destination normal in bytes,
92		it's ignored if srcNormPtr is NULL.
93		@param blendWeightStride The stride of blend weight buffer in bytes.
94		@param blendIndexStride The stride of blend index buffer in bytes.
95		@param numWeightsPerVertex Number of blend weights per-vertex, as well
96		as for blend indices.
97		@param numVertices Number of vertices to blend.
98		*/
99		virtual void softwareVertexSkinning(
100		const float srcPosPtr, float destPosPtr,
101		const float srcNormPtr, float destNormPtr,
102		const float blendWeightPtr, const unsigned char blendIndexPtr,
103		const Affine3* const* blendMatrices,
104		size_t srcPosStride, size_t destPosStride,
105		size_t srcNormStride, size_t destNormStride,
106		size_t blendWeightStride, size_t blendIndexStride,
107		size_t numWeightsPerVertex,
108		size_t numVertices) = 0;
109
110		/** Performs a software vertex morph, of the kind used for
111		morph animation although it can be used for other purposes.
112
113		This function will linearly interpolate positions between two
114		source buffers, into a third buffer.
115		@param t Parametric distance between the start and end positions
116		@param srcPos1 Pointer to buffer for the start positions
117		@param srcPos2 Pointer to buffer for the end positions
118		@param dstPos Pointer to buffer for the destination positions
119		@param pos1VSize, pos2VSize, dstVSize Vertex sizes in bytes of each of the 3 buffers referenced
120		@param numVertices Number of vertices to morph, which agree with
121		the number in start, end and destination buffer. Bear in mind
122		three floating-point values per vertex
123		@param morphNormals
124		*/
125		virtual void softwareVertexMorph(
126		float t,
127		const float srcPos1, const float srcPos2,
128		float *dstPos,
129		size_t pos1VSize, size_t pos2VSize, size_t dstVSize,
130		size_t numVertices,
131		bool morphNormals) = 0;
132
133		/** Concatenate an affine matrix to an array of affine matrices.
134		@note
135		An affine matrix is a 4x4 matrix with row 3 equal to (0, 0, 0, 1),
136		e.g. no projective coefficients.
137		@param baseMatrix The matrix used as first operand.
138		@param srcMatrices An array of matrix used as second operand.
139		@param dstMatrices An array of matrix to store matrix concatenate results.
140		@param numMatrices Number of matrices in the array.
141		*/
142		virtual void concatenateAffineMatrices(
143		const Affine3& baseMatrix,
144		const Affine3* srcMatrices,
145		Affine3* dstMatrices,
146		size_t numMatrices) = 0;
147
148		/** Calculate the face normals for the triangles based on position
149		information.
150		@param positions Pointer to position information, which packed in
151		(x, y, z) format, indexing by vertex index in the triangle. No
152		alignment requests.
153		@param triangles The triangles need to calculate face normal, the vertex
154		positions is indexed by vertex index to position information.
155		@param faceNormals The array of Vector4 used to store triangles face normal,
156		Must be aligned to SIMD alignment.
157		@param numTriangles Number of triangles to calculate face normal.
158		*/
159		virtual void calculateFaceNormals(
160		const float *positions,
161		const EdgeData::Triangle *triangles,
162		Vector4 *faceNormals,
163		size_t numTriangles) = 0;
164
165		/** Calculate the light facing state of the triangle's face normals
166
167		This is normally the first stage of calculating a silhouette, i.e.
168		establishing which tris are facing the light and which are facing
169		away.
170		@param lightPos 4D position of the light in object space, note that
171		for directional lights (which have no position), the w component
172		is 0 and the x/y/z position are the direction.
173		@param faceNormals An array of face normals for the triangles, the face
174		normal are unit vector orthogonal to the triangles, plus distance
175		from origin. This array must be aligned to SIMD alignment.
176		@param lightFacings An array of flags for store light facing state
177		results, the result flag is true if corresponding face normal facing
178		the light, false otherwise. This array no alignment requires.
179		@param numFaces Number of face normals to calculate.
180		*/
181		virtual void calculateLightFacing(
182		const Vector4& lightPos,
183		const Vector4* faceNormals,
184		char* lightFacings,
185		size_t numFaces) = 0;
186
187		/** Extruding vertices by a fixed distance based on light position.
188		@param lightPos 4D light position, when w=0.0f this represents a
189		directional light, otherwise, w must be equal to 1.0f, which
190		represents a point light.
191		@param extrudeDist The distance to extrude.
192		@param srcPositions Pointer to source vertex's position buffer, which
193		the position is a 3D vector packed in xyz format. No SIMD alignment
194		requirement but loss performance for unaligned data.
195		@param destPositions Pointer to destination vertex's position buffer,
196		which the position is a 3D vector packed in xyz format. No SIMD
197		alignment requirement but loss performance for unaligned data.
198		@param numVertices Number of vertices need to extruding, which agree
199		with source and destination buffers.
200		*/
201		virtual void extrudeVertices(
202		const Vector4& lightPos,
203		Real extrudeDist,
204		const float* srcPositions,
205		float* destPositions,
206		size_t numVertices) = 0;
207		};
208
209		/** Returns raw offsetted of the given pointer.
210		@note
211		The offset are in bytes, no matter what type of the pointer.
212		*/
213		template <class T>
214		static OGRE_FORCE_INLINE const T* rawOffsetPointer(const T* ptr, ptrdiff_t offset)
215	0	{
216	0	return (const T)((const char)(ptr) + offset);
217	0	} Unexecuted instantiation: OgreOptimisedUtilGeneral.cpp:float const* Ogre::rawOffsetPointer<float>(float const, long) Unexecuted instantiation: OgreOptimisedUtilGeneral.cpp:unsigned char const Ogre::rawOffsetPointer<unsigned char>(unsigned char const, long) Unexecuted instantiation: OgreOptimisedUtilSSE.cpp:unsigned char const Ogre::rawOffsetPointer<unsigned char>(unsigned char const, long) Unexecuted instantiation: OgreOptimisedUtilSSE.cpp:float const Ogre::rawOffsetPointer<float>(float const*, long)
218
219		template <class T>
220		static OGRE_FORCE_INLINE T* rawOffsetPointer(T* ptr, ptrdiff_t offset)
221	0	{
222	0	return (T)((char)(ptr) + offset);
223	0	} Unexecuted instantiation: OgreOptimisedUtilGeneral.cpp:float* Ogre::rawOffsetPointer<float>(float, long) Unexecuted instantiation: OgreOptimisedUtilSSE.cpp:float Ogre::rawOffsetPointer<float>(float*, long)
224
225		/** Advance the pointer with raw offset.
226		@note
227		The offset are in bytes, no matter what type of the pointer.
228		*/
229		template <class T>
230		static OGRE_FORCE_INLINE void advanceRawPointer(const T*& ptr, ptrdiff_t offset)
231	0	{
232	0	ptr = rawOffsetPointer(ptr, offset);
233	0	} Unexecuted instantiation: OgreOptimisedUtilGeneral.cpp:void Ogre::advanceRawPointer<float>(float const&, long) Unexecuted instantiation: OgreOptimisedUtilGeneral.cpp:void Ogre::advanceRawPointer<unsigned char>(unsigned char const&, long) Unexecuted instantiation: OgreOptimisedUtilSSE.cpp:void Ogre::advanceRawPointer<float>(float const&, long) Unexecuted instantiation: OgreOptimisedUtilSSE.cpp:void Ogre::advanceRawPointer<unsigned char>(unsigned char const&, long)
234
235		template <class T>
236		static OGRE_FORCE_INLINE void advanceRawPointer(T*& ptr, ptrdiff_t offset)
237	0	{
238	0	ptr = rawOffsetPointer(ptr, offset);
239	0	} Unexecuted instantiation: OgreOptimisedUtilGeneral.cpp:void Ogre::advanceRawPointer<float>(float&, long) Unexecuted instantiation: OgreOptimisedUtilSSE.cpp:void Ogre::advanceRawPointer<float>(float&, long)
240		/** @} */
241		/** @} */
242
243		}
244
245		#endif // __OptimisedUtil_H__