Package org.lwjgl.util.tootle

Class Tootle

java.lang.Object
org.lwjgl.util.tootle.Tootle
public class Tootle extends Object
Bindings to AMD Tootle.

AMD Tootle (Triangle Order Optimization Tool) is a 3D triangle mesh optimization library that improves on existing mesh preprocessing techniques. By using AMD Tootle, developers can optimize their models for pixel overdraw as well as vertex cache performance. This can provide significant performance improvements in pixel limited situations, with no penalty in vertex-limited scenarios, and no runtime cost.

Features

  • Vertex cache optimization: Triangles are re-ordered to optimize for the post-transform vertex cache in modern GPUs. This will yield significant performance improvements in vertex-tranform limited scenes.
  • Overdraw optimization: To reduce the pixel cost of rendering a mesh, the AMD Tootle library further re-orders the triangles in the mesh to reduce pixel overdraw. Significant reductions in pixel overdraw (2x or higher) can be achieved. This can yield significant performance improvements in pixel-limited scenes, and incurs no penalty in vertex-limited scenarios.
  • Vertex prefetch cache optimization: Triangle indices are re-indexed in the order of their occurrence in the triangle list. The vertex buffer is re-ordered to match these new indices. Thus, vertices are accessed close to each other in memory. This optimization exploits the input vertex cache because vertices are typically fetched in a cacheline (that may contains more than one vertex data).

The Direct3D optimizers are currently not supported.

  • Field Details

    • TOOTLE_DEFAULT_VCACHE_SIZE

      public static final int TOOTLE_DEFAULT_VCACHE_SIZE
      The default vertex cache size.
      See Also:

    • TOOTLE_MAX_FACES

      public static final int TOOTLE_MAX_FACES
      The maximum allowed number of faces in the mesh.
      See Also:

    • TOOTLE_MAX_VERTICES

      public static final int TOOTLE_MAX_VERTICES
      The maximum allowed number of vertices in the mesh.
      See Also:

    • TOOTLE_DEFAULT_ALPHA

      public static final float TOOTLE_DEFAULT_ALPHA
      The parameter for FastOptimize to create more clusters (lower number generates more clusters).

      This parameter decides where to put extra breaks to create more clusters (refer to the SIGGRAPH 2007 paper for the full description of the parameter).

      See Also:

    • TOOTLE_OK

      public static final int TOOTLE_OK
      Enumeration for Tootle return codes. (TootleResult)
      Enum values:
      • OK - All is well
      • INVALID_ARGS - Illegal arguments were passed.
      • OUT_OF_MEMORY - Tootle ran out of memory while trying to complete the call.
      • 3D_API_ERROR - Errors occurred while setting up the 3D API. This generally means that D3D isn't installed properly.
      • INTERNAL_ERROR - Something happened that really, really shouldn't.
      • NOT_INITIALIZED - Tootle was not initialized before a function call.
      See Also:

    • TOOTLE_INVALID_ARGS

      public static final int TOOTLE_INVALID_ARGS
      Enumeration for Tootle return codes. (TootleResult)
      Enum values:
      • OK - All is well
      • INVALID_ARGS - Illegal arguments were passed.
      • OUT_OF_MEMORY - Tootle ran out of memory while trying to complete the call.
      • 3D_API_ERROR - Errors occurred while setting up the 3D API. This generally means that D3D isn't installed properly.
      • INTERNAL_ERROR - Something happened that really, really shouldn't.
      • NOT_INITIALIZED - Tootle was not initialized before a function call.
      See Also:

    • TOOTLE_OUT_OF_MEMORY

      public static final int TOOTLE_OUT_OF_MEMORY
      Enumeration for Tootle return codes. (TootleResult)
      Enum values:
      • OK - All is well
      • INVALID_ARGS - Illegal arguments were passed.
      • OUT_OF_MEMORY - Tootle ran out of memory while trying to complete the call.
      • 3D_API_ERROR - Errors occurred while setting up the 3D API. This generally means that D3D isn't installed properly.
      • INTERNAL_ERROR - Something happened that really, really shouldn't.
      • NOT_INITIALIZED - Tootle was not initialized before a function call.
      See Also:

    • TOOTLE_3D_API_ERROR

      public static final int TOOTLE_3D_API_ERROR
      Enumeration for Tootle return codes. (TootleResult)
      Enum values:
      • OK - All is well
      • INVALID_ARGS - Illegal arguments were passed.
      • OUT_OF_MEMORY - Tootle ran out of memory while trying to complete the call.
      • 3D_API_ERROR - Errors occurred while setting up the 3D API. This generally means that D3D isn't installed properly.
      • INTERNAL_ERROR - Something happened that really, really shouldn't.
      • NOT_INITIALIZED - Tootle was not initialized before a function call.
      See Also:

    • TOOTLE_INTERNAL_ERROR

      public static final int TOOTLE_INTERNAL_ERROR
      Enumeration for Tootle return codes. (TootleResult)
      Enum values:
      • OK - All is well
      • INVALID_ARGS - Illegal arguments were passed.
      • OUT_OF_MEMORY - Tootle ran out of memory while trying to complete the call.
      • 3D_API_ERROR - Errors occurred while setting up the 3D API. This generally means that D3D isn't installed properly.
      • INTERNAL_ERROR - Something happened that really, really shouldn't.
      • NOT_INITIALIZED - Tootle was not initialized before a function call.
      See Also:

    • TOOTLE_NOT_INITIALIZED

      public static final int TOOTLE_NOT_INITIALIZED
      Enumeration for Tootle return codes. (TootleResult)
      Enum values:
      • OK - All is well
      • INVALID_ARGS - Illegal arguments were passed.
      • OUT_OF_MEMORY - Tootle ran out of memory while trying to complete the call.
      • 3D_API_ERROR - Errors occurred while setting up the 3D API. This generally means that D3D isn't installed properly.
      • INTERNAL_ERROR - Something happened that really, really shouldn't.
      • NOT_INITIALIZED - Tootle was not initialized before a function call.
      See Also:

    • TOOTLE_CCW

      public static final int TOOTLE_CCW
      Enumeration for face winding order. (TootleFaceWinding)
      Enum values:
      • CCW - Face is ordered counter-clockwise
      • CW - Face is ordered clockwise
      See Also:

    • TOOTLE_CW

      public static final int TOOTLE_CW
      Enumeration for face winding order. (TootleFaceWinding)
      Enum values:
      • CCW - Face is ordered counter-clockwise
      • CW - Face is ordered clockwise
      See Also:

    • TOOTLE_VCACHE_AUTO

      public static final int TOOTLE_VCACHE_AUTO
      Enumeration for the algorithm for vertex optimization. (TootleVCacheOptimizer)
      Enum values:
      • VCACHE_AUTO - If vertex cache size is less than 7, use LSTRIPS algorithm otherwise TIPSY.
      • VCACHE_DIRECT3D - Use D3DXOptimizeFaces to optimize faces.
      • VCACHE_LSTRIPS - Build a list like triangle strips to optimize faces.
      • VCACHE_TIPSY - Use TIPSY (the algorithm from SIGGRAPH 2007) to optimize faces.
      See Also:

    • TOOTLE_VCACHE_DIRECT3D

      public static final int TOOTLE_VCACHE_DIRECT3D
      Enumeration for the algorithm for vertex optimization. (TootleVCacheOptimizer)
      Enum values:
      • VCACHE_AUTO - If vertex cache size is less than 7, use LSTRIPS algorithm otherwise TIPSY.
      • VCACHE_DIRECT3D - Use D3DXOptimizeFaces to optimize faces.
      • VCACHE_LSTRIPS - Build a list like triangle strips to optimize faces.
      • VCACHE_TIPSY - Use TIPSY (the algorithm from SIGGRAPH 2007) to optimize faces.
      See Also:

    • TOOTLE_VCACHE_LSTRIPS

      public static final int TOOTLE_VCACHE_LSTRIPS
      Enumeration for the algorithm for vertex optimization. (TootleVCacheOptimizer)
      Enum values:
      • VCACHE_AUTO - If vertex cache size is less than 7, use LSTRIPS algorithm otherwise TIPSY.
      • VCACHE_DIRECT3D - Use D3DXOptimizeFaces to optimize faces.
      • VCACHE_LSTRIPS - Build a list like triangle strips to optimize faces.
      • VCACHE_TIPSY - Use TIPSY (the algorithm from SIGGRAPH 2007) to optimize faces.
      See Also:

    • TOOTLE_VCACHE_TIPSY

      public static final int TOOTLE_VCACHE_TIPSY
      Enumeration for the algorithm for vertex optimization. (TootleVCacheOptimizer)
      Enum values:
      • VCACHE_AUTO - If vertex cache size is less than 7, use LSTRIPS algorithm otherwise TIPSY.
      • VCACHE_DIRECT3D - Use D3DXOptimizeFaces to optimize faces.
      • VCACHE_LSTRIPS - Build a list like triangle strips to optimize faces.
      • VCACHE_TIPSY - Use TIPSY (the algorithm from SIGGRAPH 2007) to optimize faces.
      See Also:

    • TOOTLE_OVERDRAW_AUTO

      public static final int TOOTLE_OVERDRAW_AUTO
      Enumeration for the algorithm for overdraw optimization. (TootleOverdrawOptimizer)
      Enum values:
      • OVERDRAW_AUTO - Use either Direct3D or raytracing to reorder clusters (depending on the number of clusters).
      • OVERDRAW_DIRECT3D - Use Direct3D rendering to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_RAYTRACE - Use CPU raytracing to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_FAST - Use a fast approximation algorithm (from SIGGRAPH 2007) to reorder clusters.
      See Also:

    • TOOTLE_OVERDRAW_DIRECT3D

      public static final int TOOTLE_OVERDRAW_DIRECT3D
      Enumeration for the algorithm for overdraw optimization. (TootleOverdrawOptimizer)
      Enum values:
      • OVERDRAW_AUTO - Use either Direct3D or raytracing to reorder clusters (depending on the number of clusters).
      • OVERDRAW_DIRECT3D - Use Direct3D rendering to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_RAYTRACE - Use CPU raytracing to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_FAST - Use a fast approximation algorithm (from SIGGRAPH 2007) to reorder clusters.
      See Also:

    • TOOTLE_OVERDRAW_RAYTRACE

      public static final int TOOTLE_OVERDRAW_RAYTRACE
      Enumeration for the algorithm for overdraw optimization. (TootleOverdrawOptimizer)
      Enum values:
      • OVERDRAW_AUTO - Use either Direct3D or raytracing to reorder clusters (depending on the number of clusters).
      • OVERDRAW_DIRECT3D - Use Direct3D rendering to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_RAYTRACE - Use CPU raytracing to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_FAST - Use a fast approximation algorithm (from SIGGRAPH 2007) to reorder clusters.
      See Also:

    • TOOTLE_OVERDRAW_FAST

      public static final int TOOTLE_OVERDRAW_FAST
      Enumeration for the algorithm for overdraw optimization. (TootleOverdrawOptimizer)
      Enum values:
      • OVERDRAW_AUTO - Use either Direct3D or raytracing to reorder clusters (depending on the number of clusters).
      • OVERDRAW_DIRECT3D - Use Direct3D rendering to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_RAYTRACE - Use CPU raytracing to reorder clusters to optimize overdraw (slow O(N^2)).
      • OVERDRAW_FAST - Use a fast approximation algorithm (from SIGGRAPH 2007) to reorder clusters.
      See Also:

  • Method Details

    • TootleInit

      public static int TootleInit()
      Performs one-time initialization required by Tootle.

    • nTootleOptimizeVCache

      public static int nTootleOptimizeVCache(long pnIB, int nFaces, int nVertices, int nCacheSize, long pnIBOut, long pnFaceRemapOut, int eVCacheOptimizer)
      Unsafe version of: OptimizeVCache
      Parameters:
      nFaces - the number of faces in the index buffer. This must be non-zero and less than MAX_FACES.

    • TootleOptimizeVCache

      public static int TootleOptimizeVCache(IntBuffer pnIB, int nVertices, int nCacheSize, @Nullable IntBuffer pnIBOut, @Nullable IntBuffer pnFaceRemapOut, int eVCacheOptimizer)
      This function performs vertex cache optimization on an index buffer. It returns a face re-mapping if requested.
      Parameters:
      pnIB - the index buffer to optimize. Must be a triangle list.
      nVertices - the number of vertices in the model. This must non-zero and less than MAX_VERTICES.
      nCacheSize - the number of vertices that will fit in cache. If the application does not know or care about the vertex cache size, then it should pass DEFAULT_VCACHE_SIZE. This value must be non-zero.
      pnIBOut - a pointer that will be filled with an optimized index buffer. May be NULL. May equal pnIB.
      pnFaceRemapOut - a pointer to an array that will be filled with a face re-mapping. May be NULL. This is an array of nFaces elements.

      Element i in the array will contain the position of input face i in the output face ordering.

      eVCacheOptimizer - the selection for choosing the algorithm to optimize vertex cache. One of:
      VCACHE_AUTOVCACHE_DIRECT3DVCACHE_LSTRIPSVCACHE_TIPSY
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleClusterMesh

      public static int nTootleClusterMesh(long pVB, long pnIB, int nVertices, int nFaces, int nVBStride, int nTargetClusters, long pnClusteredIBOut, long pnFaceClustersOut, long pnFaceRemapOut)
      Unsafe version of: ClusterMesh
      Parameters:
      nVertices - number of vertices. This must be non-zero and less than MAX_VERTICES.
      nFaces - number of faces. This must be non-zero and less than MAX_FACES.

    • TootleClusterMesh

      public static int TootleClusterMesh(ByteBuffer pVB, IntBuffer pnIB, int nVBStride, int nTargetClusters, IntBuffer pnClusteredIBOut, IntBuffer pnFaceClustersOut, @Nullable IntBuffer pnFaceRemapOut)
      This function partitions a mesh into a set of connected, roughly planar clusters. It generates a new mesh that is re-arranged in cluster order. This clustering is required as a pre-cursor to overdraw optimization. This function returns a mesh that is clustered. That is, the faces are sorted in ascending order by cluster ID. The number of clusters in the mesh will be equal to pFaceClustersOut[ nFaces-1 ] + 1.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - an index buffer. Must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      nTargetClusters - a target number of clusters. The clustering algorithm will create at least this many clusters, but not more than nFaces. This value is only a hint. More clusters may be created if Tootle considers it necessary. (for example, if there are numerous connected components in the mesh).

      Passing 0 for this value causes Tootle to use an automatic method to determine when to stop creating clusters.

      pnClusteredIBOut - an array that will receive a copy of the index buffer, sorted by cluster ID. May not be NULL. May equal pnIB.
      pnFaceClustersOut - an array of nFaces+1 unsigned ints, that will be filled with the cluster ID that was assigned to each face in the output index buffer. The last element of the array contains the number of cluster. This is of a full format type. May not be NULL.
      pnFaceRemapOut - an array that will receive a face re-mapping. May be NULL. If not NULL, must be an array of size nFaces. The i'th element of the output array contains the position of input face i in the new face ordering.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • TootleClusterMesh

      public static int TootleClusterMesh(FloatBuffer pVB, IntBuffer pnIB, int nVBStride, int nTargetClusters, IntBuffer pnClusteredIBOut, IntBuffer pnFaceClustersOut, @Nullable IntBuffer pnFaceRemapOut)
      This function partitions a mesh into a set of connected, roughly planar clusters. It generates a new mesh that is re-arranged in cluster order. This clustering is required as a pre-cursor to overdraw optimization. This function returns a mesh that is clustered. That is, the faces are sorted in ascending order by cluster ID. The number of clusters in the mesh will be equal to pFaceClustersOut[ nFaces-1 ] + 1.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - an index buffer. Must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      nTargetClusters - a target number of clusters. The clustering algorithm will create at least this many clusters, but not more than nFaces. This value is only a hint. More clusters may be created if Tootle considers it necessary. (for example, if there are numerous connected components in the mesh).

      Passing 0 for this value causes Tootle to use an automatic method to determine when to stop creating clusters.

      pnClusteredIBOut - an array that will receive a copy of the index buffer, sorted by cluster ID. May not be NULL. May equal pnIB.
      pnFaceClustersOut - an array of nFaces+1 unsigned ints, that will be filled with the cluster ID that was assigned to each face in the output index buffer. The last element of the array contains the number of cluster. This is of a full format type. May not be NULL.
      pnFaceRemapOut - an array that will receive a face re-mapping. May be NULL. If not NULL, must be an array of size nFaces. The i'th element of the output array contains the position of input face i in the new face ordering.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleFastOptimizeVCacheAndClusterMesh

      public static int nTootleFastOptimizeVCacheAndClusterMesh(long pnIB, int nFaces, int nVertices, int nCacheSize, long pnIBOut, long pnClustersOut, long pnNumClustersOut, float fAlpha)
      Unsafe version of: FastOptimizeVCacheAndClusterMesh
      Parameters:
      nFaces - the number of faces in the index buffer

    • TootleFastOptimizeVCacheAndClusterMesh

      public static int TootleFastOptimizeVCacheAndClusterMesh(IntBuffer pnIB, int nVertices, int nCacheSize, IntBuffer pnIBOut, IntBuffer pnClustersOut, IntBuffer pnNumClustersOut, float fAlpha)
      This function performs vertex cache optimization and clustering the mesh based on the algorithm from SIGGRAPH 2007. It produces the re-ordered index buffer and an array of the resulting clusters. The result can be used as inputs to OptimizeOverdraw.
      Parameters:
      pnIB - the input index buffer: 3 unsigned int per triangle.
      nVertices - the number of vertices in the vertex buffer
      nCacheSize - hardware cache size (12 to 24 are good options)
      pnIBOut - the updated index buffer (the output). May not be NULL. May equal pnIB.
      pnClustersOut - the output clusters which is an array of nFaces+1 unsigned ints. It is of a compact format type. Entry i and i+1 mark all face ids in [i, i+1) to be in cluster i. The last element of the array contains the number of clusters. May not be NULL. This has to be pre-allocated of size nFaces+1.
      pnNumClustersOut - the total number of clusters in pnClustersOut
      fAlpha - a linear parameter to compute lambda term from the algorithm. Pass DEFAULT_ALPHA as a default.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleOptimizeOverdraw

      public static int nTootleOptimizeOverdraw(long pVB, long pnIB, int nVertices, int nFaces, int nVBStride, long pfViewpoint, int nViewpoints, int eFrontWinding, long pnFaceClusters, long pnIBOut, long pnClusterRemapOut, int eOverdrawOptimizer)
      Unsafe version of: OptimizeOverdraw
      Parameters:
      nVertices - the number of vertices in the mesh. This must be non-zero and less than MAX_VERTICES.
      nFaces - the number of faces in the mesh. This must be non-zero and less than MAX_FACES.
      nViewpoints - the number of viewpoints in the viewpoint array

    • TootleOptimizeOverdraw

      public static int TootleOptimizeOverdraw(ByteBuffer pVB, IntBuffer pnIB, int nVBStride, @Nullable FloatBuffer pfViewpoint, int eFrontWinding, IntBuffer pnFaceClusters, @Nullable IntBuffer pnIBOut, @Nullable IntBuffer pnClusterRemapOut, int eOverdrawOptimizer)
      Given a clustered mesh, this function computes a cluster ordering that minimizes expected overdraw, and sorts the clusters according to this ordering. The input is a mesh whose faces are seperated into clusters. The clustering can be obtained by calling ClusterMesh, or the application can supply its own clustering.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the mesh index buffer. This must be a triangle list. The faces must be clustered.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      pfViewpoint - an array of viewpoints to use to measure overdraw. Each viewpoint must be a point on or in the unit sphere. When measuring overdraw, the mesh will be scaled and translated so that it lies inside the unit sphere. The mesh will be rendered with orthographic projections, with the camera centered at the given point looking at the origin. If this argument is NULL, a default viewpoint set will be used.
      eFrontWinding - the winding order of front-faces in the mesh. One of:
      CCWCW
      pnFaceClusters - this array of nFaces+1 size can be either of two types: a full format (the output of ClusterMesh) or a compact format (the output of FastOptimizeVCacheAndClusterMesh).

      The full format is an array of mapping for each face to the cluster ID. The entry i of this array contains the cluster ID of face i.

      The compact format is an array that maps every face ID between entry i and i+1 to be in cluster i.

      For both formats, the last entry of the array ( pnFaceClusters[ nFaces ] ) should contains the number of total clusters.

      pnIBOut - an array that will receive the re-ordered index buffer. May be NULL. May equal pnIB.
      pnClusterRemapOut - an array that will receive the cluster ordering. May be NULL. If non-null, the size of the array must be equal to the number of clusters in the mesh. pClusterRemapOut[i] will be set to the ID of the cluster that should come i'th in the draw order.
      eOverdrawOptimizer - the algorithm selection for optimizing overdraw. One of:
      OVERDRAW_AUTOOVERDRAW_DIRECT3DOVERDRAW_RAYTRACEOVERDRAW_FAST
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS 3D_API_ERROR, NOT_INITIALIZED

    • TootleOptimizeOverdraw

      public static int TootleOptimizeOverdraw(FloatBuffer pVB, IntBuffer pnIB, int nVBStride, @Nullable FloatBuffer pfViewpoint, int eFrontWinding, IntBuffer pnFaceClusters, @Nullable IntBuffer pnIBOut, @Nullable IntBuffer pnClusterRemapOut, int eOverdrawOptimizer)
      Given a clustered mesh, this function computes a cluster ordering that minimizes expected overdraw, and sorts the clusters according to this ordering. The input is a mesh whose faces are seperated into clusters. The clustering can be obtained by calling ClusterMesh, or the application can supply its own clustering.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the mesh index buffer. This must be a triangle list. The faces must be clustered.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      pfViewpoint - an array of viewpoints to use to measure overdraw. Each viewpoint must be a point on or in the unit sphere. When measuring overdraw, the mesh will be scaled and translated so that it lies inside the unit sphere. The mesh will be rendered with orthographic projections, with the camera centered at the given point looking at the origin. If this argument is NULL, a default viewpoint set will be used.
      eFrontWinding - the winding order of front-faces in the mesh. One of:
      CCWCW
      pnFaceClusters - this array of nFaces+1 size can be either of two types: a full format (the output of ClusterMesh) or a compact format (the output of FastOptimizeVCacheAndClusterMesh).

      The full format is an array of mapping for each face to the cluster ID. The entry i of this array contains the cluster ID of face i.

      The compact format is an array that maps every face ID between entry i and i+1 to be in cluster i.

      For both formats, the last entry of the array ( pnFaceClusters[ nFaces ] ) should contains the number of total clusters.

      pnIBOut - an array that will receive the re-ordered index buffer. May be NULL. May equal pnIB.
      pnClusterRemapOut - an array that will receive the cluster ordering. May be NULL. If non-null, the size of the array must be equal to the number of clusters in the mesh. pClusterRemapOut[i] will be set to the ID of the cluster that should come i'th in the draw order.
      eOverdrawOptimizer - the algorithm selection for optimizing overdraw. One of:
      OVERDRAW_AUTOOVERDRAW_DIRECT3DOVERDRAW_RAYTRACEOVERDRAW_FAST
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS 3D_API_ERROR, NOT_INITIALIZED

    • TootleCleanup

      public static void TootleCleanup()
      Frees all resources held by Tootle.

    • nTootleOptimize

      public static int nTootleOptimize(long pVB, long pnIB, int nVertices, int nFaces, int nVBStride, int nCacheSize, long pViewpoints, int nViewpoints, int eFrontWinding, long pnIBOut, long pnNumClustersOut, int eVCacheOptimizer, int eOverdrawOptimizer)
      Unsafe version of: Optimize
      Parameters:
      nVertices - number of vertices. This must be non-zero and less than MAX_VERTICES.
      nFaces - number of faces. This must be non-zero and less than MAX_FACES.
      nViewpoints - the number of viewpoints in the viewpoint array

    • TootleOptimize

      public static int TootleOptimize(ByteBuffer pVB, IntBuffer pnIB, int nVBStride, int nCacheSize, @Nullable FloatBuffer pViewpoints, int eFrontWinding, IntBuffer pnIBOut, @Nullable IntBuffer pnNumClustersOut, int eVCacheOptimizer, int eOverdrawOptimizer)
      This is a utility function that is provided for developers to perform the entire optimization for a mesh.

      The function calls the three core functions to create clusters for the mesh (ClusterMesh), optimize vertex cache for each cluster (VCacheClusters), and reorder the clusters to optimize overdraw (OptimizeOverdraw). It generates a new indices for faces that is optimized for post-transform vertex cache and overdraw.

      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - an index buffer. Must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      nCacheSize - the number of vertices that will fit in cache. If the application does not know or care about the vertex cache size, then it should pass DEFAULT_VCACHE_SIZE. This value must be non-zero.
      pViewpoints - an array of viewpoints to use to measure overdraw. Each viewpoint must be a point on or in the unit sphere. When measuring overdraw, the mesh will be scaled and translated so that it lies inside the unit sphere. The mesh will be rendered with orthographic projections, with the camera centered at the given point looking at the origin. If this argument is NULL, a default viewpoint set will be used.
      eFrontWinding - the winding order of front-faces in the model. One of:
      CCWCW
      pnIBOut - a pointer that will be filled with an optimized index buffer. May not be NULL. May equal pIB.
      pnNumClustersOut - the number of clusters generated by the algorithm. May be NULL if the output is not requested.
      eVCacheOptimizer - the selection for choosing the algorithm to optimize vertex cache. One of:
      VCACHE_AUTOVCACHE_DIRECT3DVCACHE_LSTRIPSVCACHE_TIPSY
      eOverdrawOptimizer - the algorithm selection for optimizing overdraw. One of:
      OVERDRAW_AUTOOVERDRAW_DIRECT3DOVERDRAW_RAYTRACEOVERDRAW_FAST
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • TootleOptimize

      public static int TootleOptimize(FloatBuffer pVB, IntBuffer pnIB, int nVBStride, int nCacheSize, @Nullable FloatBuffer pViewpoints, int eFrontWinding, IntBuffer pnIBOut, @Nullable IntBuffer pnNumClustersOut, int eVCacheOptimizer, int eOverdrawOptimizer)
      This is a utility function that is provided for developers to perform the entire optimization for a mesh.

      The function calls the three core functions to create clusters for the mesh (ClusterMesh), optimize vertex cache for each cluster (VCacheClusters), and reorder the clusters to optimize overdraw (OptimizeOverdraw). It generates a new indices for faces that is optimized for post-transform vertex cache and overdraw.

      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - an index buffer. Must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      nCacheSize - the number of vertices that will fit in cache. If the application does not know or care about the vertex cache size, then it should pass DEFAULT_VCACHE_SIZE. This value must be non-zero.
      pViewpoints - an array of viewpoints to use to measure overdraw. Each viewpoint must be a point on or in the unit sphere. When measuring overdraw, the mesh will be scaled and translated so that it lies inside the unit sphere. The mesh will be rendered with orthographic projections, with the camera centered at the given point looking at the origin. If this argument is NULL, a default viewpoint set will be used.
      eFrontWinding - the winding order of front-faces in the model. One of:
      CCWCW
      pnIBOut - a pointer that will be filled with an optimized index buffer. May not be NULL. May equal pIB.
      pnNumClustersOut - the number of clusters generated by the algorithm. May be NULL if the output is not requested.
      eVCacheOptimizer - the selection for choosing the algorithm to optimize vertex cache. One of:
      VCACHE_AUTOVCACHE_DIRECT3DVCACHE_LSTRIPSVCACHE_TIPSY
      eOverdrawOptimizer - the algorithm selection for optimizing overdraw. One of:
      OVERDRAW_AUTOOVERDRAW_DIRECT3DOVERDRAW_RAYTRACEOVERDRAW_FAST
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleFastOptimize

      public static int nTootleFastOptimize(long pVB, long pnIB, int nVertices, int nFaces, int nVBStride, int nCacheSize, int eFrontWinding, long pnIBOut, long pnNumClustersOut, float fAlpha)
      Unsafe version of: FastOptimize
      Parameters:
      nVertices - the number of vertices in the vertex buffer
      nFaces - the number of faces in the index buffer

    • TootleFastOptimize

      public static int TootleFastOptimize(ByteBuffer pVB, IntBuffer pnIB, int nVBStride, int nCacheSize, int eFrontWinding, IntBuffer pnIBOut, @Nullable IntBuffer pnNumClustersOut, float fAlpha)
      This is a utility function that performs the entire optimization using the new algorithm from SIGGRAPH 2007. This function performs vertex cache optimization and clustering, then optimize overdraw on the clusters generated. It generates a new indices for faces that is optimized for post-transform vertex cache and overdraw.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the input index buffer: 3 unsigned int per triangle
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      nCacheSize - hardware cache size (12 to 24 are good options)
      eFrontWinding - the winding order of front-faces in the model. One of:
      CCWCW
      pnIBOut - the updated index buffer (the output). May not be NULL. May equal pnIB.
      pnNumClustersOut - the number of output clusters. May be NULL if not requested.
      fAlpha - a linear parameter to compute lambda term from the algorithm. Pass DEFAULT_ALPHA as a default.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • TootleFastOptimize

      public static int TootleFastOptimize(FloatBuffer pVB, IntBuffer pnIB, int nVBStride, int nCacheSize, int eFrontWinding, IntBuffer pnIBOut, @Nullable IntBuffer pnNumClustersOut, float fAlpha)
      This is a utility function that performs the entire optimization using the new algorithm from SIGGRAPH 2007. This function performs vertex cache optimization and clustering, then optimize overdraw on the clusters generated. It generates a new indices for faces that is optimized for post-transform vertex cache and overdraw.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the input index buffer: 3 unsigned int per triangle
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      nCacheSize - hardware cache size (12 to 24 are good options)
      eFrontWinding - the winding order of front-faces in the model. One of:
      CCWCW
      pnIBOut - the updated index buffer (the output). May not be NULL. May equal pnIB.
      pnNumClustersOut - the number of output clusters. May be NULL if not requested.
      fAlpha - a linear parameter to compute lambda term from the algorithm. Pass DEFAULT_ALPHA as a default.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleVCacheClusters

      public static int nTootleVCacheClusters(long pnIB, int nFaces, int nVertices, int nCacheSize, long pnFaceClusters, long pnIBOut, long pnFaceRemapOut, int eVCacheOptimizer)
      Unsafe version of: VCacheClusters
      Parameters:
      nFaces - the number of faces in the index buffer. This must be non-zero and less than MAX_FACES.

    • TootleVCacheClusters

      public static int TootleVCacheClusters(IntBuffer pnIB, int nVertices, int nCacheSize, IntBuffer pnFaceClusters, @Nullable IntBuffer pnIBOut, @Nullable IntBuffer pnFaceRemapOut, int eVCacheOptimizer)
      This is a utility function to optimize vertex cache on a clustered index buffer. This function simply calls OptimizeVCache repeatedly. The faces within each cluster will be re-ordered, but the clustering will be maintained.
      Parameters:
      pnIB - the index buffer to optimize. Must be a triangle list.
      nVertices - the number of vertices in the model. This must be non-zero and less than MAX_VERTICES.
      nCacheSize - the number of vertices that will fit in cache. If the application does not know or care about the vertex cache size, then it should pass DEFAULT_VCACHE_SIZE. This value must be non-zero.
      pnFaceClusters - an array giving the cluster ID for each face. All faces in a particular cluster should appear consecutively in the index buffer, as well as in this array. It should be of size nFaces+1.
      pnIBOut - a pointer that will be filled with an optimized index buffer. May be NULL. May equal pnIB.
      pnFaceRemapOut - a pointer to an array that will be filled with a face re-mapping. May be NULL. This is an array of nFaces elements.

      Element i in the array will contain the position of input face i in the output face ordering.

      eVCacheOptimizer - the selection for choosing the algorithm to optimize vertex cache. One of:
      VCACHE_AUTOVCACHE_DIRECT3DVCACHE_LSTRIPSVCACHE_TIPSY
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleMeasureCacheEfficiency

      public static int nTootleMeasureCacheEfficiency(long pnIB, int nFaces, int nCacheSize, long pfEfficiencyOut)
      Unsafe version of: MeasureCacheEfficiency
      Parameters:
      nFaces - the number of faces in the index buffer. This must be non-zero and less than MAX_FACES.

    • TootleMeasureCacheEfficiency

      public static int TootleMeasureCacheEfficiency(IntBuffer pnIB, int nCacheSize, FloatBuffer pfEfficiencyOut)
      A utility function to simulate vertex processing and measures the cache efficiency of an index buffer.

      The return cache efficiency is the ACMR (Average Cache Miss Ratio) of the mesh. It ranges between 0.5 to 3. 0.5 is the best optimal value, 3 is the worst ratio.

      Parameters:
      pnIB - the index buffer whose efficiency should be measured. Must be a triangle list.
      nCacheSize - the number of vertices that will fit in cache. If the application doesn't know or care, it should use DEFAULT_VCACHE_SIZE.
      pfEfficiencyOut - a pointer to receive the vertex cache efficiency. This is defined as the number of cache misses per triangle.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • nTootleMeasureOverdraw

      public static int nTootleMeasureOverdraw(long pVB, long pnIB, int nVertices, int nFaces, int nVBStride, long pfViewpoint, int nViewpoints, int eFrontWinding, long pfAvgODOut, long pfMaxODOut, int eOverdrawOptimizer)
      Unsafe version of: MeasureOverdraw
      Parameters:
      nVertices - the number of vertices. This must be non-zero and less than MAX_VERTICES.
      nFaces - the number of indices. This must be non-zero and less than MAX_FACES.
      nViewpoints - the number of viewpoints in the viewpoint array

    • TootleMeasureOverdraw

      public static int TootleMeasureOverdraw(ByteBuffer pVB, IntBuffer pnIB, int nVBStride, @Nullable FloatBuffer pfViewpoint, int eFrontWinding, @Nullable FloatBuffer pfAvgODOut, @Nullable FloatBuffer pfMaxODOut, int eOverdrawOptimizer)
      A utility function to measure the amount of overdraw that occurs over a set of views. Overdraw is defined as the number of pixels rendered divided by the number of pixels covered by an object, minus one.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the index buffer. Must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      pfViewpoint - an array of viewpoints to use to measure overdraw. Each viewpoint must be a point on or in the unit sphere. When measuring overdraw, the mesh will be scaled and translated so that it lies inside the unit sphere. The mesh will be rendered with orthographic projections, with the camera centered at the given point looking at the origin. If this argument is NULL, a default viewpoint set will be used.
      eFrontWinding - the winding order of front-faces in the model
      pfAvgODOut - a pointer to a variable to receive the average overdraw per pixel. May be NULL.
      pfMaxODOut - a pointer to a variable to receive the maximum overdraw per pixel. May be NULL.
      eOverdrawOptimizer - the algorithm selection for optimizing overdraw. One of:
      OVERDRAW_AUTOOVERDRAW_DIRECT3DOVERDRAW_RAYTRACEOVERDRAW_FAST
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS, NOT_INITIALIZED

    • TootleMeasureOverdraw

      public static int TootleMeasureOverdraw(FloatBuffer pVB, IntBuffer pnIB, int nVBStride, @Nullable FloatBuffer pfViewpoint, int eFrontWinding, @Nullable FloatBuffer pfAvgODOut, @Nullable FloatBuffer pfMaxODOut, int eOverdrawOptimizer)
      A utility function to measure the amount of overdraw that occurs over a set of views. Overdraw is defined as the number of pixels rendered divided by the number of pixels covered by an object, minus one.
      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the index buffer. Must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      pfViewpoint - an array of viewpoints to use to measure overdraw. Each viewpoint must be a point on or in the unit sphere. When measuring overdraw, the mesh will be scaled and translated so that it lies inside the unit sphere. The mesh will be rendered with orthographic projections, with the camera centered at the given point looking at the origin. If this argument is NULL, a default viewpoint set will be used.
      eFrontWinding - the winding order of front-faces in the model
      pfAvgODOut - a pointer to a variable to receive the average overdraw per pixel. May be NULL.
      pfMaxODOut - a pointer to a variable to receive the maximum overdraw per pixel. May be NULL.
      eOverdrawOptimizer - the algorithm selection for optimizing overdraw. One of:
      OVERDRAW_AUTOOVERDRAW_DIRECT3DOVERDRAW_RAYTRACEOVERDRAW_FAST
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS, NOT_INITIALIZED

    • nTootleOptimizeVertexMemory

      public static int nTootleOptimizeVertexMemory(long pVB, long pnIB, int nVertices, int nFaces, int nVBStride, long pVBOut, long pnIBOut, long pnVertexRemapOut)
      Unsafe version of: OptimizeVertexMemory
      Parameters:
      nVertices - the number of vertices in the mesh. This must be non-zero and less than MAX_VERTICES.
      nFaces - the number of faces in the mesh. This must be non-zero and less than MAX_FACES.

    • TootleOptimizeVertexMemory

      public static int TootleOptimizeVertexMemory(ByteBuffer pVB, IntBuffer pnIB, int nVBStride, ByteBuffer pVBOut, IntBuffer pnIBOut, @Nullable IntBuffer pnVertexRemapOut)
      This function rearranges the vertex buffer's memory location based on the index buffer.

      Call this function after you have optimized the index buffer for vertex cache post-tranform and/or overdraw. The idea is to rearrange the memory location for vertex buffer such that it will be optimized for vertex prefetch cache. Typically vertices are fetched in a cacheline (more than one vertex at a time). Thus, the vertex in the next memory location will come for free if they are processed next in line. This is what we want to exploit. It will compute a new Vertex Buffer and Index Buffer (since the vertices have been reordered).

      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the mesh index buffer. This must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      pVBOut - the output vertex buffer. May be NULL. May equal pVB.
      pnIBOut - the output index buffer. May not be NULL. May equal pnIB.
      pnVertexRemapOut - an array that will receive a vertex re-mapping. May be NULL if the output is not requested. If not NULL, must be an array of size nVertices. The i'th element of the output array contains the position of the input vertex i in the new vertex re-ordering.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS

    • TootleOptimizeVertexMemory

      public static int TootleOptimizeVertexMemory(FloatBuffer pVB, IntBuffer pnIB, int nVBStride, FloatBuffer pVBOut, IntBuffer pnIBOut, @Nullable IntBuffer pnVertexRemapOut)
      This function rearranges the vertex buffer's memory location based on the index buffer.

      Call this function after you have optimized the index buffer for vertex cache post-tranform and/or overdraw. The idea is to rearrange the memory location for vertex buffer such that it will be optimized for vertex prefetch cache. Typically vertices are fetched in a cacheline (more than one vertex at a time). Thus, the vertex in the next memory location will come for free if they are processed next in line. This is what we want to exploit. It will compute a new Vertex Buffer and Index Buffer (since the vertices have been reordered).

      Parameters:
      pVB - a pointer to the vertex buffer. The pointer pVB must point to the vertex position. The vertex position must be a 3-component floating point value (X,Y,Z).
      pnIB - the mesh index buffer. This must be a triangle list.
      nVBStride - the distance between successive vertices in the vertex buffer, in bytes. This must be at least 3*sizeof(float).
      pVBOut - the output vertex buffer. May be NULL. May equal pVB.
      pnIBOut - the output index buffer. May not be NULL. May equal pnIB.
      pnVertexRemapOut - an array that will receive a vertex re-mapping. May be NULL if the output is not requested. If not NULL, must be an array of size nVertices. The i'th element of the output array contains the position of the input vertex i in the new vertex re-ordering.
      Returns:
      one of: OK, OUT_OF_MEMORY, INVALID_ARGS