GU_Grid.h

Go to the documentation of this file.

/*
 * Copyright (c) 2024
 *      Side Effects Software Inc.  All rights reserved.
 *
 * Redistribution and use of Houdini Development Kit samples in source and
 * binary forms, with or without modification, are permitted provided that the
 * following conditions are met:
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. The name of Side Effects Software may not be used to endorse or
 *    promote products derived from this software without specific prior
 *    written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY SIDE EFFECTS SOFTWARE `AS IS' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
 * NO EVENT SHALL SIDE EFFECTS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *----------------------------------------------------------------------------
 * Definition of GU_GridT structure to aid in iterating over grids.
 */

#pragma once

#ifndef __HDK_GU_GRID__
#define __HDK_GU_GRID__

#include <GEO/GEO_SurfaceType.h>
#include <GA/GA_Types.h>
#include <UT/UT_Assert.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Types.h>

namespace HDK_Sample {

template<typename INT_TYPE=GA_Offset>
struct GU_GridT
{
    /// These are the number of edge rows and edge columns.
    /// @{
    exint myNumEdgeRows;
    exint myNumEdgeCols;
    /// @}

    /// These members specify the points of the grid
    /// @{
    INT_TYPE myCorners[4];
    INT_TYPE myRow0Start;
    union {
        INT_TYPE myRow0Step;
        INT_TYPE *myRow0Array;
    };
    INT_TYPE myRow1Start;
    union {
        INT_TYPE myRow1Step;
        INT_TYPE *myRow1Array;
    };
    INT_TYPE myCol0Start;
    union {
        INT_TYPE myCol0Step;
        INT_TYPE *myCol0Array;
    };
    INT_TYPE myCol1Start;
    union {
        INT_TYPE myCol1Step;
        INT_TYPE *myCol1Array;
    };
    INT_TYPE myMiddleStart;
    INT_TYPE myMiddleColStep;
    INT_TYPE myMiddleRowStep;
    /// @}

    GEO_SurfaceType mySurfaceType;

    enum class PrimitiveType : unsigned char {
        POLYGON,
        MESH,
        NURBS,
        BEZIER,
        POLYSOUP,
        POINTS
    };

    PrimitiveType myPrimitiveType;

    /// NOTE: Basis orders for NURBS and Bezier surfaces must be in the range
    ///       [2,GA_MAX_ORDER], which fits in 4 bits, since GA_MAX_ORDER==11.
    unsigned char myBasisOrderU:4;
    unsigned char myBasisOrderV:4;
    SYS_STATIC_ASSERT(GA_MAX_ORDER < 16);

    /// If mySurfaceType is rows, cols, or rows and cols, and a particular
    /// row or column wraps around (row0[col]==row1[col] or col0[row]==col1[row]),
    /// This indicates to create an open curve with an extra vertex (if true),
    /// instead of a closed polygon (if false).
    bool myUnrollCurves:1;

    /// If mySurfaceType is rows or rows and cols, and columns aren't wrapped,
    /// if this is true, the first row is present (the usual), else it's not
    /// (e.g. the grid might be connected to an existing mesh).
    bool myFirstRowIfNotWrapped:1;

    /// If mySurfaceType is rows or rows and cols, and columns aren't wrapped,
    /// if this is true, the final row is present (the usual), else it's not
    /// (e.g. the grid might be connected to an existing mesh).
    bool myLastRowIfNotWrapped:1;

    /// If mySurfaceType is cols or rows and cols, and rows aren't wrapped,
    /// if this is true, the first col is present (the usual), else it's not
    /// (e.g. the grid might be connected to an existing mesh).
    bool myFirstColIfNotWrapped:1;

    /// If mySurfaceType is cols or rows and cols, and rows aren't wrapped,
    /// if this is true, the final col is present (the usual), else it's not
    /// (e.g. the grid might be connected to an existing mesh).
    bool myLastColIfNotWrapped:1;

    /// If adjacent points on the boundary are equal, and mySurfaceType is
    /// one of the triangle options or quads, the appropriate polygons
    /// will be simple triangles, instead of quads or pairs of triangles.
    /// If a boundary quad becomes fully degenerate, no polygon will be output
    /// for it.
    bool myTriangularPoles:1;

    /// If myPrimitiveType is NURBS or BEZIER, and mySurfaceType is
    /// GEO_PATCH_ROWS or GEO_PATCH_COLS or GEO_PATCH_ROWCOL, this
    /// indicates whether to create separate curve primitives (true),
    /// or a surface primitive with its surface type set correspondingly.
    bool myCurvesIfBasisRowCol:1;

    /// NOTE: The following members are cached values computed from the members
    ///       above, not used for input.
    ///       After setting the other members, either precompute() must be
    ///       called or these members must be manually set, before any other
    ///       functions can be called.
    /// @{
    bool myAllWrapU:1;
    bool myAllWrapV:1;
    bool myNoWrapU:1;
    bool myNoWrapV:1;
    exint myNumPrimitives;
    exint myNumVertices;
    /// @}

    /// NOTE: The bools can't be in-class initialized, since they're bitfields,
    ///       and the C++ standard evidently missed the case of bitfields.
    /// NOTE: The row and col starts are non-negative, so that destructing
    ///       a default constructed grid won't crash.
    GU_GridT()
        : myRow0Start(0)
        , myRow1Start(0)
        , myCol0Start(0)
        , myCol1Start(0)
        , mySurfaceType(GEO_PATCH_QUADS)
        , myPrimitiveType(PrimitiveType::POLYGON)
        , myUnrollCurves(false)
        , myFirstRowIfNotWrapped(true)
        , myLastRowIfNotWrapped(true)
        , myFirstColIfNotWrapped(true)
        , myLastColIfNotWrapped(true)
        , myTriangularPoles(false)
        , myCurvesIfBasisRowCol(false)
    {}
    ~GU_GridT() { clear(); }

    /// This computes myAllWrapU, myAllWrapV, myNoWrapU, and myNoWrapV
    /// after everything else is set.
    void precompute();

    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstRowIfNotWrapped, myLastRowIfNotWrapped, myFirstColIfNotWrapped,
    ///       and myLastColIfNotWrapped if rows/cols/rowcol.
    /// NOTE: You don't need to call precompute() after this.
    void initSingleGrid(exint nedgerows, exint nedgecols, INT_TYPE start_pt=INT_TYPE(0));

    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstRowIfNotWrapped, myLastRowIfNotWrapped,
    ///       and myUnrollCurves if rows/cols/rowcol.
    /// NOTE: You don't need to call precompute() after this.
    void initColTube(exint nedgerows, exint nedgecols, INT_TYPE start_pt=INT_TYPE(0));

    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstColIfNotWrapped, myLastColIfNotWrapped,
    ///       and myUnrollCurves if rows/cols/rowcol.
    /// NOTE: You don't need to call precompute() after this.
    void initRowTube(exint nedgerows, exint nedgecols, INT_TYPE start_pt=INT_TYPE(0));

    /// This is the sphere most people expect, with north and south poles (row=0/nedgerows).
    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstRowIfNotWrapped, myLastRowIfNotWrapped,
    ///       and myUnrollCurves if rows/cols/rowcol, or
    ///       myTriangularPoles if quads/tris.
    /// NOTE: You'll probably want to set myFirstRowIfNotWrapped and
    ///       myLastRowIfNotWrapped to false, to match the Sphere SOP.
    /// NOTE: You don't need to call precompute() after this.
    void initColSphere(exint nedgerows, exint nedgecols,
        INT_TYPE start_pt=INT_TYPE(0), INT_TYPE end_pt=INT_TYPE(1),
        INT_TYPE start_mid_pt=INT_TYPE(2));

    /// This is the sphere most people DON'T expect, with east and west poles (col=0/nedgecols).
    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstColIfNotWrapped, myLastColIfNotWrapped,
    ///       and myUnrollCurves if rows/cols/rowcol, or
    ///       myTriangularPoles if quads/tris.
    /// NOTE: You'll probably want to set myFirstColIfNotWrapped and
    ///       myLastColIfNotWrapped to false, to match the Sphere SOP.
    /// NOTE: You don't need to call precompute() after this.
    void initRowSphere(exint nedgerows, exint nedgecols,
        INT_TYPE start_pt=INT_TYPE(0), INT_TYPE end_pt=INT_TYPE(1),
        INT_TYPE start_mid_pt=INT_TYPE(2));

    /// This is effectively a slice of a col sphere, with north and south poles (row=0/nedgerows).
    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstRowIfNotWrapped, myLastRowIfNotWrapped,
    ///       and myUnrollCurves if rows/cols/rowcol, or
    ///       myTriangularPoles if quads/tris.
    /// NOTE: You'll probably want to set myFirstRowIfNotWrapped and
    ///       myLastRowIfNotWrapped to false, to match the Sphere SOP.
    /// NOTE: You don't need to call precompute() after this.
    void initSplitColSphere(exint nedgerows, exint nedgecols,
        INT_TYPE start_pt=INT_TYPE(0), INT_TYPE end_pt=INT_TYPE(1),
        INT_TYPE start_mid_pt=INT_TYPE(2));

    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myUnrollCurves if rows/cols/rowcol.
    /// NOTE: You don't need to call precompute() after this.
    void initTorus(exint nedgerows, exint nedgecols, INT_TYPE start_pt=INT_TYPE(0));

    /// NOTE: mySurfaceType & myPrimitiveType must be set before calling, and so should
    ///       myFirstRowIfNotWrapped, myLastRowIfNotWrapped,
    ///       and myUnrollCurves if rows/cols/rowcol, or
    ///       myTriangularPoles if quads/tris.
    /// NOTE: You'll probably want to set myFirstRowIfNotWrapped or
    ///       myLastRowIfNotWrapped to false, depending on row0_pole.
    /// NOTE: You don't need to call precompute() after this.
    void initColCone(exint nedgerows, exint nedgecols, bool row0_pole=true,
        INT_TYPE start_pt=INT_TYPE(0), INT_TYPE start_mid_pt=INT_TYPE(1));

    /// Free memory allocations owned by this.
    /// NOTE: This intentionally does not clear myPrimitiveType,
    ///       mySurfaceType, myBasisOrderU, myBasisOrderV, or myUnrollCurves.
    void clear()
    {
        if (myRow0Start < INT_TYPE(0))
        {
            delete [] myRow0Array;
            myRow0Start = INT_TYPE(0);
        }
        if (myRow1Start < INT_TYPE(0))
        {
            delete [] myRow1Array;
            myRow1Start = INT_TYPE(0);
        }
        if (myCol0Start < INT_TYPE(0))
        {
            delete [] myCol0Array;
            myCol0Start = INT_TYPE(0);
        }
        if (myCol1Start < INT_TYPE(0))
        {
            delete [] myCol1Array;
            myCol1Start = INT_TYPE(0);
        }
    }

    INT_TYPE getPoint(exint row, exint col) const
    {
        UT_ASSERT_P(row >= 0 && row <= myNumEdgeRows);
        UT_ASSERT_P(col >= 0 && col <= myNumEdgeCols);
        if (row == 0)
        {
            if (col == 0)
                return myCorners[0];
            if (col == myNumEdgeCols)
                return myCorners[1];
            --col;
            return (myRow0Start < INT_TYPE(0)) ? myRow0Array[col] : (myRow0Start + myRow0Step*col);
        }
        if (row == myNumEdgeRows)
        {
            if (col == 0)
                return myCorners[2];
            if (col == myNumEdgeCols)
                return myCorners[3];
            --col;
            return (myRow1Start < INT_TYPE(0)) ? myRow1Array[col] : (myRow1Start + myRow1Step*col);
        }
        --row;
        if (col == 0)
            return (myCol0Start < INT_TYPE(0)) ? myCol0Array[row] : (myCol0Start + myCol0Step*row);
        if (col == myNumEdgeCols)
            return (myCol1Start < INT_TYPE(0)) ? myCol1Array[row] : (myCol1Start + myCol1Step*row);
        --col;
        return myMiddleStart + myMiddleRowStep*row + myMiddleColStep*col;
    }

    bool doesRowWrap(exint row) const
    {
        if (row == 0)
            return myCorners[0] == myCorners[1];
        if (row == myNumEdgeRows)
            return myCorners[2] == myCorners[3];
        UT_ASSERT_P(row > 0 && row < myNumEdgeRows);
        --row;
        INT_TYPE pt0 = (myCol0Start < INT_TYPE(0)) ? myCol0Array[row] : (myCol0Start + myCol0Step*row);
        INT_TYPE pt1 = (myCol1Start < INT_TYPE(0)) ? myCol1Array[row] : (myCol1Start + myCol1Step*row);
        return pt0 == pt1;
    }
    bool doesColWrap(exint col) const
    {
        if (col == 0)
            return myCorners[0] == myCorners[2];
        if (col == myNumEdgeCols)
            return myCorners[1] == myCorners[3];
        UT_ASSERT_P(col > 0 && col < myNumEdgeCols);
        --col;
        INT_TYPE pt0 = (myRow0Start < INT_TYPE(0)) ? myRow0Array[col] : (myRow0Start + myRow0Step*col);
        INT_TYPE pt1 = (myRow1Start < INT_TYPE(0)) ? myRow1Array[col] : (myRow1Start + myRow1Step*col);
        return pt0 == pt1;
    }

    // Adjusts the points of the grid such that the effective starting point is different.
    void shiftPoints(INT_TYPE shift)
    {
        for (int i = 0; i < 4; ++i)
            myCorners[i] += shift;

        if (myRow0Start >= INT_TYPE(0))
            myRow0Start += shift;
        else
        {
            for (exint col = 1; col < myNumEdgeCols; ++col)
                myRow0Array[col-1] += shift;
        }
        if (myRow1Start >= INT_TYPE(0))
            myRow1Start += shift;
        else
        {
            for (exint col = 1; col < myNumEdgeCols; ++col)
                myRow1Array[col-1] += shift;
        }
        if (myCol0Start >= INT_TYPE(0))
            myCol0Start += shift;
        else
        {
            for (exint row = 1; row < myNumEdgeRows; ++row)
                myCol0Array[row-1] += shift;
        }
        if (myCol1Start >= INT_TYPE(0))
            myCol1Start += shift;
        else
        {
            for (exint row = 1; row < myNumEdgeRows; ++row)
                myCol1Array[row-1] += shift;
        }
        myMiddleStart += shift;
    }

    bool isInvalidTPSurf() const
    {
        const bool is_nurbs = (myPrimitiveType == PrimitiveType::NURBS);
        const bool is_bezier = (myPrimitiveType == PrimitiveType::BEZIER);

        if (!is_nurbs && !is_bezier)
            return false;

        // If number of row vertices or col vertices is smaller than
        // the corresponding basis order, reject this grid.
        exint nvtxrows = myNumEdgeRows + exint(myNoWrapV || myUnrollCurves);
        exint nvtxcols = myNumEdgeCols + exint(myNoWrapU || myUnrollCurves);
        if (nvtxrows < myBasisOrderV || nvtxcols < myBasisOrderU)
            return true;
        // Beziers need the edge count along an axis to be a multiple of (order-1)
        if (is_bezier && ((myNumEdgeRows % (myBasisOrderV-1)) != 0 || (myNumEdgeCols % (myBasisOrderU-1)) != 0))
            return true;
        return false;
    }

    void fixTPSurf()
    {
        const bool is_nurbs = (myPrimitiveType == PrimitiveType::NURBS);
        const bool is_bezier = (myPrimitiveType == PrimitiveType::BEZIER);
        if (!is_nurbs && !is_bezier)
            return;

        // Order must be between 2 and GA_MAX_ORDER (inclusive).
        myBasisOrderU = SYSclamp(int(myBasisOrderU), 2, GA_MAX_ORDER);
        myBasisOrderV = SYSclamp(int(myBasisOrderV), 2, GA_MAX_ORDER);

        // If number of row vertices or col vertices is smaller than
        // the corresponding basis order, increase it.
        const exint nvtxrows = myNumEdgeRows + exint(myNoWrapV || myUnrollCurves);
        const exint nvtxcols = myNumEdgeCols + exint(myNoWrapU || myUnrollCurves);
        if (nvtxrows < myBasisOrderV)
            myNumEdgeRows += myBasisOrderV-nvtxrows;
        if (nvtxcols < myBasisOrderU)
            myNumEdgeCols += myBasisOrderU-nvtxcols;
        if (is_bezier)
        {
            // Beziers need the edge count along an axis to be a multiple of (order-1)
            const exint row_excess = myNumEdgeRows % (myBasisOrderV-1);
            const exint col_excess = myNumEdgeCols % (myBasisOrderU-1);
            if (row_excess != 0)
                myNumEdgeRows += (myBasisOrderV-1) - row_excess;
            if (col_excess != 0)
                myNumEdgeCols += (myBasisOrderU-1) - col_excess;
        }
    }
};

using GU_Grid = GU_GridT<GA_Offset>;

} // End of HDK_Sample namespace

#endif