padstack.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2024 Jon Evans <[email protected]>
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef KICAD_PADSTACK_H
#define KICAD_PADSTACK_H
 
#include <memory>
#include <optional>
#include <wx/string.h>
 
#include <api/serializable.h>
#include <geometry/eda_angle.h>
#include <layer_ids.h>
#include <lset.h>
#include <math/vector2d.h>
#include <properties/property.h>
#include <zones.h>
 
class BOARD_ITEM;
class PCB_SHAPE;
 
namespace kiapi::board::types
{
    class PadStack;
    class PadStackLayer;
}
 

enum class PAD_SHAPE : int
{
    CIRCLE,
    RECTANGLE,      // do not use just RECT: it collides in a header on MSYS2
    OVAL,
    TRAPEZOID,
    ROUNDRECT,
 
    // Rectangle with a chamfered corner ( and with rounded other corners).
    CHAMFERED_RECT,
    CUSTOM            // A shape defined by user, using a set of basic shapes
                      // (thick segments, circles, arcs, polygons).
};

enum class PAD_DRILL_SHAPE
{
    UNDEFINED,
    CIRCLE,
    OBLONG,
};
 
enum class PAD_DRILL_POST_MACHINING_MODE
{
    UNKNOWN,
    NOT_POST_MACHINED,
    COUNTERBORE,
    COUNTERSINK
};
 
enum class BACKDRILL_MODE
{
    NO_BACKDRILL,
    BACKDRILL_BOTTOM,
    BACKDRILL_TOP,
    BACKDRILL_BOTH
};

enum class PAD_ATTRIB
{
    PTH,        
    SMD,        
    CONN,       
    NPTH,       
};
 

enum class PAD_PROP
{
    NONE,                  
    BGA,                   
    FIDUCIAL_GLBL,         
    FIDUCIAL_LOCAL,        
    TESTPOINT,             
    HEATSINK,              
    CASTELLATED,           
    MECHANICAL,            
    PRESSFIT               
};
 
 
enum class UNCONNECTED_LAYER_MODE
{
    KEEP_ALL,
    START_END_ONLY,
    REMOVE_ALL,
    REMOVE_EXCEPT_START_AND_END
};
 
 
enum class CUSTOM_SHAPE_ZONE_MODE
{
    OUTLINE,
    CONVEXHULL
};
 

class PADSTACK : public SERIALIZABLE
{
public:
    enum class TYPE
    {
        NORMAL,     
        VIA,        
        MOUNTING    
    };

    enum class MODE
    {
        NORMAL,           
        FRONT_INNER_BACK, 
        CUSTOM            
    };

    static constexpr PCB_LAYER_ID ALL_LAYERS = F_Cu;

    static constexpr PCB_LAYER_ID INNER_LAYERS = In1_Cu;

    struct SHAPE_PROPS
    {
        PAD_SHAPE shape;    
        PAD_SHAPE anchor_shape; 
        VECTOR2I size;  
 
        /*
         * Most of the time the hole is the center of the shape (m_Offset = 0). But some designers
         * use oblong/rect pads with a hole moved to one of the oblong/rect pad shape ends.
         * In all cases the hole is at the pad position.  This offset is from the hole to the center
         * of the pad shape (ie: the copper area around the hole).
         * ShapePos() returns the board shape position according to the offset and the pad rotation.
         */
        VECTOR2I offset; 
 
        double round_rect_radius_ratio;
        double chamfered_rect_ratio;    
        int chamfered_rect_positions;   

        VECTOR2I trapezoid_delta_size;
 
        SHAPE_PROPS();
        bool operator==( const SHAPE_PROPS& aOther ) const;
        int Compare( const SHAPE_PROPS& aOther ) const;
    };

    struct COPPER_LAYER_PROPS
    {
        SHAPE_PROPS shape;
        std::optional<ZONE_CONNECTION> zone_connection;
        std::optional<int> thermal_spoke_width;
        std::optional<EDA_ANGLE> thermal_spoke_angle;
        std::optional<int> thermal_gap;
        std::optional<int> clearance;
 
        /*
         * Editing definitions of primitives for custom pad shapes.  In local coordinates relative
         * to m_Pos (NOT shapePos) at orient 0.
         */
        std::vector<std::shared_ptr<PCB_SHAPE>> custom_shapes;
 
        bool operator==( const COPPER_LAYER_PROPS& aOther ) const;
        int Compare( const COPPER_LAYER_PROPS& aOther ) const;
 
        double Similarity( const COPPER_LAYER_PROPS& aOther ) const;
    };

    struct MASK_LAYER_PROPS
    {
        std::optional<int> solder_mask_margin;
        std::optional<int> solder_paste_margin;
        std::optional<double> solder_paste_margin_ratio;
 
        std::optional<bool> has_solder_mask;   
        std::optional<bool> has_solder_paste;  
        std::optional<bool> has_covering; 
        std::optional<bool> has_plugging; 
 
        bool operator==( const MASK_LAYER_PROPS& aOther ) const;
        int Compare( const MASK_LAYER_PROPS& aOther ) const;
    };

    struct DRILL_PROPS
    {
        VECTOR2I size;  
        PAD_DRILL_SHAPE shape;
        PCB_LAYER_ID start;
        PCB_LAYER_ID end;
 
        std::optional<bool> is_filled; 
        std::optional<bool> is_capped; 
 
        bool operator==( const DRILL_PROPS& aOther ) const;
        int Compare( const DRILL_PROPS& aOther ) const;
    };
 
    struct POST_MACHINING_PROPS
    {
        std::optional<PAD_DRILL_POST_MACHINING_MODE> mode;
        int size = 0;
        int depth = 0;
        int angle = 0;
 
        bool operator==( const POST_MACHINING_PROPS& aOther ) const;
        int Compare( const POST_MACHINING_PROPS& aOther ) const;
    };
 
public:
    PADSTACK( BOARD_ITEM* aParent );
    virtual ~PADSTACK() = default;
    PADSTACK( const PADSTACK& aOther );
    PADSTACK& operator=( const PADSTACK &aOther );
 
    bool operator==( const PADSTACK& aOther ) const;
    bool operator!=( const PADSTACK& aOther ) const { return !operator==( aOther ); }
 
    void Serialize( google::protobuf::Any &aContainer ) const override;
    bool Deserialize( const google::protobuf::Any &aContainer ) override;

    static int Compare( const PADSTACK* aPadstackRef, const PADSTACK* aPadstackCmp );

    bool HasExplicitDefinitionForLayer( PCB_LAYER_ID aLayer ) const;

    double Similarity( const PADSTACK& aOther ) const;
 
    const LSET& LayerSet() const { return m_layerSet; }
    LSET& LayerSet() { return m_layerSet; }
    void SetLayerSet( const LSET& aSet ) { m_layerSet = aSet; }

    void FlipLayers( BOARD* aBoard );
 
    PCB_LAYER_ID StartLayer() const;
    PCB_LAYER_ID EndLayer() const;
 
    MODE Mode() const { return m_mode; }
    void SetMode( MODE aMode );

    wxString Name() const;
 
    EDA_ANGLE GetOrientation() const { return m_orientation; }
    void SetOrientation( EDA_ANGLE aAngle )
    {
        m_orientation = aAngle;
        m_orientation.Normalize();
    }
 
    DRILL_PROPS& Drill() { return m_drill; }
    const DRILL_PROPS& Drill() const { return m_drill; }
 
    DRILL_PROPS& SecondaryDrill() { return m_secondaryDrill; }
    const DRILL_PROPS& SecondaryDrill() const { return m_secondaryDrill; }
 
    DRILL_PROPS& TertiaryDrill() { return m_tertiaryDrill; }
    const DRILL_PROPS& TertiaryDrill() const { return m_tertiaryDrill; }
 
    POST_MACHINING_PROPS& FrontPostMachining() { return m_frontPostMachining; }
    const POST_MACHINING_PROPS& FrontPostMachining() const { return m_frontPostMachining; }
 
    POST_MACHINING_PROPS& BackPostMachining() { return m_backPostMachining; }
    const POST_MACHINING_PROPS& BackPostMachining() const { return m_backPostMachining; }
 
    UNCONNECTED_LAYER_MODE UnconnectedLayerMode() const { return m_unconnectedLayerMode; }
    void SetUnconnectedLayerMode( UNCONNECTED_LAYER_MODE aMode ) { m_unconnectedLayerMode = aMode; }
 
    COPPER_LAYER_PROPS& CopperLayer( PCB_LAYER_ID aLayer );
    const COPPER_LAYER_PROPS& CopperLayer( PCB_LAYER_ID aLayer ) const;
 
    MASK_LAYER_PROPS& FrontOuterLayers() { return m_frontMaskProps; }
    const MASK_LAYER_PROPS& FrontOuterLayers() const { return m_frontMaskProps; }
 
    MASK_LAYER_PROPS& BackOuterLayers() { return m_backMaskProps; }
    const MASK_LAYER_PROPS& BackOuterLayers() const { return m_backMaskProps; }

    std::optional<bool> IsTented( PCB_LAYER_ID aSide ) const;
 
    std::optional<bool> IsCovered( PCB_LAYER_ID aSide ) const;
 
    std::optional<bool> IsPlugged( PCB_LAYER_ID aSide ) const;
 
    std::optional<bool> IsCapped() const;
 
    std::optional<bool> IsFilled() const;
 
    CUSTOM_SHAPE_ZONE_MODE CustomShapeInZoneMode() const { return m_customShapeInZoneMode; }
    void SetCustomShapeInZoneMode( CUSTOM_SHAPE_ZONE_MODE aM ) { m_customShapeInZoneMode = aM; }

    void ForEachUniqueLayer( const std::function<void( PCB_LAYER_ID )>& aMethod ) const;
 
    std::vector<PCB_LAYER_ID> UniqueLayers() const;

    PCB_LAYER_ID EffectiveLayerFor( PCB_LAYER_ID aLayer ) const;

    LSET RelevantShapeLayers( const PADSTACK& aOther ) const;
 
    // The following section has convenience getters for the padstack properties on a given layer.
 
    PAD_SHAPE Shape( PCB_LAYER_ID aLayer ) const;
    void SetShape( PAD_SHAPE aShape, PCB_LAYER_ID aLayer );
 
    // Setter rather than direct access to enforce only positive sizes
    void SetSize( const VECTOR2I& aSize, PCB_LAYER_ID aLayer );
    const VECTOR2I& Size( PCB_LAYER_ID aLayer ) const;
 
    PAD_DRILL_SHAPE DrillShape() const;
    void SetDrillShape( PAD_DRILL_SHAPE aShape );
 
    VECTOR2I& Offset( PCB_LAYER_ID aLayer );
    const VECTOR2I& Offset( PCB_LAYER_ID aLayer ) const;
 
    PAD_SHAPE AnchorShape( PCB_LAYER_ID aLayer ) const;
    void SetAnchorShape( PAD_SHAPE aShape, PCB_LAYER_ID aLayer );
 
    VECTOR2I& TrapezoidDeltaSize( PCB_LAYER_ID aLayer );
    const VECTOR2I& TrapezoidDeltaSize( PCB_LAYER_ID aLayer ) const;
 
    double RoundRectRadiusRatio( PCB_LAYER_ID aLayer ) const;
    void SetRoundRectRadiusRatio( double aRatio, PCB_LAYER_ID aLayer );
 
    int RoundRectRadius( PCB_LAYER_ID aLayer ) const;
    void SetRoundRectRadius( double aRadius, PCB_LAYER_ID aLayer );
 
    double ChamferRatio( PCB_LAYER_ID aLayer ) const;
    void SetChamferRatio( double aRatio, PCB_LAYER_ID aLayer );
 
    int& ChamferPositions( PCB_LAYER_ID aLayer );
    const int& ChamferPositions( PCB_LAYER_ID aLayer ) const;
    void SetChamferPositions( int aPositions, PCB_LAYER_ID aLayer );
 
    std::optional<int>& Clearance( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& Clearance( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& SolderMaskMargin( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& SolderMaskMargin( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& SolderPasteMargin( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& SolderPasteMargin( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<double>& SolderPasteMarginRatio( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<double>& SolderPasteMarginRatio( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<ZONE_CONNECTION>& ZoneConnection( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<ZONE_CONNECTION>& ZoneConnection( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& ThermalSpokeWidth( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& ThermalSpokeWidth( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    std::optional<int>& ThermalGap( PCB_LAYER_ID aLayer = F_Cu );
    const std::optional<int>& ThermalGap( PCB_LAYER_ID aLayer = F_Cu ) const;
 
    EDA_ANGLE DefaultThermalSpokeAngleForShape( PCB_LAYER_ID aLayer = F_Cu ) const;
    EDA_ANGLE ThermalSpokeAngle( PCB_LAYER_ID aLayer = F_Cu ) const;
    void SetThermalSpokeAngle( EDA_ANGLE aAngle, PCB_LAYER_ID aLayer = F_Cu );
 
    std::vector<std::shared_ptr<PCB_SHAPE>>& Primitives( PCB_LAYER_ID aLayer );
    const std::vector<std::shared_ptr<PCB_SHAPE>>& Primitives( PCB_LAYER_ID aLayer ) const;

    void AddPrimitive( PCB_SHAPE* aShape, PCB_LAYER_ID aLayer );

    void AppendPrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList,
                           PCB_LAYER_ID aLayer );

    void ReplacePrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList,
                            PCB_LAYER_ID aLayer );
 
    void ClearPrimitives( PCB_LAYER_ID aLayer );
 
    BACKDRILL_MODE GetBackdrillMode() const;
    void SetBackdrillMode( BACKDRILL_MODE aMode );
 
    std::optional<int> GetBackdrillSize( bool aTop ) const;
    void SetBackdrillSize( bool aTop, std::optional<int> aSize );
 
    PCB_LAYER_ID GetBackdrillEndLayer( bool aTop ) const;
    void SetBackdrillEndLayer( bool aTop, PCB_LAYER_ID aLayer );
 
private:
    void packCopperLayer( PCB_LAYER_ID aLayer, kiapi::board::types::PadStack& aProto ) const;
 
    bool unpackCopperLayer( const kiapi::board::types::PadStackLayer& aProto );

    BOARD_ITEM* m_parent;

    MODE m_mode;

    LSET m_layerSet;

    wxString m_customName;

    EDA_ANGLE m_orientation;

    //COPPER_LAYER_PROPS m_defaultCopperProps;
    std::unordered_map<PCB_LAYER_ID, COPPER_LAYER_PROPS> m_copperProps;

    MASK_LAYER_PROPS m_frontMaskProps;

    MASK_LAYER_PROPS m_backMaskProps;
 
    UNCONNECTED_LAYER_MODE m_unconnectedLayerMode;

    CUSTOM_SHAPE_ZONE_MODE m_customShapeInZoneMode;

    DRILL_PROPS m_drill;

    DRILL_PROPS m_secondaryDrill;

    DRILL_PROPS m_tertiaryDrill;
 
    POST_MACHINING_PROPS m_frontPostMachining;
    POST_MACHINING_PROPS m_backPostMachining;
};
 
#ifndef SWIG
DECLARE_ENUM_TO_WXANY( PAD_DRILL_POST_MACHINING_MODE );
DECLARE_ENUM_TO_WXANY( UNCONNECTED_LAYER_MODE );
DECLARE_ENUM_TO_WXANY( BACKDRILL_MODE );
#endif
 
 
#endif //KICAD_PADSTACK_H