pad.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
 * Copyright (C) 1992-2021 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 2
 * 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, you may find one here:
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * or you may search the http://www.gnu.org website for the version 2 license,
 * or you may write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
 */

#ifndef PAD_H
#define PAD_H

#include <mutex>
#include <zones.h>
#include <board_connected_item.h>
#include <convert_to_biu.h>
#include <geometry/shape_poly_set.h>
#include <geometry/shape_compound.h>
#include <pad_shapes.h>

class PCB_SHAPE;
class PARAM_CFG;
class SHAPE;
class SHAPE_SEGMENT;

enum CUST_PAD_SHAPE_IN_ZONE
{
    CUST_PAD_SHAPE_IN_ZONE_OUTLINE,
    CUST_PAD_SHAPE_IN_ZONE_CONVEXHULL
};

class LINE_READER;
class EDA_3D_CANVAS;
class FOOTPRINT;
class FP_SHAPE;

namespace KIGFX
{
    class VIEW;
}

class PAD : public BOARD_CONNECTED_ITEM
{
public:
    PAD( FOOTPRINT* parent );

    // Copy constructor & operator= are needed because the list of basic shapes
    // must be duplicated in copy.
    PAD( const PAD& aPad );
    PAD& operator=( const PAD &aOther );

    /*
     * Default layers used for pads, according to the pad type.
     *
     * This is default values only, they can be changed for a given pad.
     */
    static LSET PTHMask();          
    static LSET SMDMask();          
    static LSET ConnSMDMask();      
    static LSET UnplatedHoleMask(); 
    static LSET ApertureMask();     

    static inline bool ClassOf( const EDA_ITEM* aItem )
    {
        return aItem && PCB_PAD_T == aItem->Type();
    }

    bool IsType( const KICAD_T aScanTypes[] ) const override
    {
        if( BOARD_CONNECTED_ITEM::IsType( aScanTypes ) )
            return true;

        for( const KICAD_T* p = aScanTypes; *p != EOT; ++p )
        {
            if( m_drill.x > 0 && m_drill.y > 0 )
            {
                if( *p == PCB_LOCATE_HOLE_T )
                    return true;
                else if( *p == PCB_LOCATE_PTH_T && m_attribute != PAD_ATTRIB::NPTH )
                    return true;
                else if( *p == PCB_LOCATE_NPTH_T && m_attribute == PAD_ATTRIB::NPTH )
                    return true;
            }
        }

        return false;
    }

    FOOTPRINT* GetParent() const;

    wxString GetParentAsString() const { return m_parent->m_Uuid.AsString(); }

    bool IsLocked() const override;

    void ImportSettingsFrom( const PAD& aMasterPad );

    bool IsFlipped() const;

    void SetNumber( const wxString& aNumber ) { m_number = aNumber; }
    const wxString& GetNumber() const { return m_number; }

    bool CanHaveNumber() const;

    void SetPinFunction( const wxString& aName ) { m_pinFunction = aName; }
    const wxString& GetPinFunction() const { return m_pinFunction; }

    void SetPinType( const wxString& aType ) { m_pinType = aType; }
    const wxString& GetPinType() const { return m_pinType; }

    bool SameLogicalPadAs( const PAD* other ) const
    {
        // hide tricks behind sensible API
        return GetParent() == other->GetParent() && m_number == other->m_number;
    }

    void SetShape( PAD_SHAPE aShape )
    {
        m_padShape = aShape;
        SetDirty();
    }

    PAD_SHAPE GetShape() const { return m_padShape; }

    void SetPosition( const wxPoint& aPos ) override
    {
        m_pos = aPos;
        SetDirty();
    }

    wxPoint GetPosition() const override { return m_pos; }

    PAD_SHAPE GetAnchorPadShape() const       { return m_anchorPadShape; }

    CUST_PAD_SHAPE_IN_ZONE GetCustomShapeInZoneOpt() const
    {
        return m_customShapeClearanceArea;
    }

    void SetCustomShapeInZoneOpt( CUST_PAD_SHAPE_IN_ZONE aOption )
    {
        m_customShapeClearanceArea = aOption;
    }

    void SetAnchorPadShape( PAD_SHAPE aShape )
    {
        m_anchorPadShape = ( aShape ==  PAD_SHAPE::RECT ) ? PAD_SHAPE::RECT : PAD_SHAPE::CIRCLE;
        SetDirty();
    }

    bool IsOnCopperLayer() const override
    {
        return ( GetLayerSet() & LSET::AllCuMask() ) != 0;
    }

    void SetY( int y )                          { m_pos.y = y; SetDirty(); }
    void SetX( int x )                          { m_pos.x = x; SetDirty(); }

    void SetPos0( const wxPoint& aPos )         { m_pos0 = aPos; }
    const wxPoint& GetPos0() const              { return m_pos0; }

    void SetY0( int y )                         { m_pos0.y = y; }
    void SetX0( int x )                         { m_pos0.x = x; }

    void SetSize( const wxSize& aSize )         { m_size = aSize; SetDirty(); }
    const wxSize& GetSize() const               { return m_size; }
    void SetSizeX( const int aX )               { m_size.x = aX; SetDirty(); }
    const int GetSizeX() const                  { return m_size.x; }
    void SetSizeY( const int aY )               { m_size.y = aY; SetDirty(); }
    const int GetSizeY() const                  { return m_size.y; }

    void SetDelta( const wxSize& aSize )        { m_deltaSize = aSize; SetDirty(); }
    const wxSize& GetDelta() const              { return m_deltaSize; }

    void SetDrillSize( const wxSize& aSize )    { m_drill = aSize; SetDirty(); }
    const wxSize& GetDrillSize() const          { return m_drill; }
    void SetDrillSizeX( const int aX )          { m_drill.x = aX; SetDirty(); }
    const int GetDrillSizeX() const             { return m_drill.x; }
    void SetDrillSizeY( const int aY )          { m_drill.y = aY; SetDirty(); }
    const int GetDrillSizeY() const             { return m_drill.y; }

    void SetOffset( const wxPoint& aOffset )    { m_offset = aOffset; SetDirty(); }
    const wxPoint& GetOffset() const            { return m_offset; }

    wxPoint GetCenter() const override          { return GetPosition(); }

    void AddPrimitivePoly( const SHAPE_POLY_SET& aPoly, int aThickness, bool aFilled );
    void AddPrimitivePoly( const std::vector<wxPoint>& aPoly, int aThickness, bool aFilled );
    void AddPrimitiveSegment( const wxPoint& aStart, const wxPoint& aEnd, int aThickness );
    void AddPrimitiveCircle( const wxPoint& aCenter, int aRadius, int aThickness, bool aFilled );
    void AddPrimitiveRect( const wxPoint& aStart, const wxPoint& aEnd, int aThickness,
                           bool aFilled );
    void AddPrimitiveArc( const wxPoint& aCenter, const wxPoint& aStart, int aArcAngle,
                          int aThickness );
    void AddPrimitiveCurve( const wxPoint& aStart, const wxPoint& aEnd, const wxPoint& aCtrl1,
                            const wxPoint& aCtrl2, int aThickness );


    bool GetBestAnchorPosition( VECTOR2I& aPos );

    void MergePrimitivesAsPolygon( SHAPE_POLY_SET* aMergedPolygon,
                                   ERROR_LOC aErrorLoc = ERROR_INSIDE ) const;

    void DeletePrimitivesList();

    const std::vector<std::shared_ptr<PCB_SHAPE>>& GetPrimitives() const
    {
        return m_editPrimitives;
    }

    void Flip( const wxPoint& aCentre, bool aFlipLeftRight ) override;

    void FlipPrimitives( bool aFlipLeftRight );

    void ReplacePrimitives( const std::vector<std::shared_ptr<PCB_SHAPE>>& aPrimitivesList );

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

    void AddPrimitive( PCB_SHAPE* aPrimitive );

    void SetOrientation( double aAngle );

    void SetOrientationDegrees( double aOrientation ) { SetOrientation( aOrientation*10.0 ); }

    double GetOrientation() const { return m_orient; }
    double GetOrientationDegrees() const   { return m_orient/10.0; }
    double GetOrientationRadians() const   { return m_orient*M_PI/1800; }

    void SetDrillShape( PAD_DRILL_SHAPE_T aShape ) { m_drillShape = aShape; m_shapesDirty = true; }
    PAD_DRILL_SHAPE_T GetDrillShape() const     { return m_drillShape; }

    bool IsDirty() const
    {
        return m_shapesDirty || m_polyDirty;
    }

    void SetDirty()
    {
        m_shapesDirty = true;
        m_polyDirty = true;
    }

    void SetLayerSet( LSET aLayers ) override   { m_layerMask = aLayers; }
    LSET GetLayerSet() const override           { return m_layerMask; }

    void SetAttribute( PAD_ATTRIB aAttribute );
    PAD_ATTRIB GetAttribute() const             { return m_attribute; }

    void SetProperty( PAD_PROP aProperty );
    PAD_PROP GetProperty() const              { return m_property; }

    // We don't currently have an attribute for APERTURE, and adding one will change the file
    // format, so for now just infer a copper-less pad to be an APERTURE pad.
    bool IsAperturePad() const
    {
        return ( m_layerMask & LSET::AllCuMask() ).none();
    }

    void SetPadToDieLength( int aLength )       { m_lengthPadToDie = aLength; }
    int GetPadToDieLength() const               { return m_lengthPadToDie; }

    int GetLocalSolderMaskMargin() const        { return m_localSolderMaskMargin; }
    void SetLocalSolderMaskMargin( int aMargin ) { m_localSolderMaskMargin = aMargin; }

    int GetLocalClearance( wxString* aSource ) const override;
    int GetLocalClearance() const               { return m_localClearance; }
    void SetLocalClearance( int aClearance )    { m_localClearance = aClearance; }

    int GetLocalSolderPasteMargin() const       { return m_localSolderPasteMargin; }
    void SetLocalSolderPasteMargin( int aMargin ) { m_localSolderPasteMargin = aMargin; }

    double GetLocalSolderPasteMarginRatio() const { return m_localSolderPasteMarginRatio; }
    void SetLocalSolderPasteMarginRatio( double aRatio ) { m_localSolderPasteMarginRatio = aRatio; }

    void TransformShapeWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer,
                                               PCB_LAYER_ID aLayer, int aClearanceValue,
                                               int aMaxError, ERROR_LOC aErrorLoc,
                                               bool ignoreLineWidth = false ) const override;

    bool TransformHoleWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, int aInflateValue,
                                              int aError, ERROR_LOC aErrorLoc ) const;

    // @copydoc BOARD_ITEM::GetEffectiveShape
    virtual std::shared_ptr<SHAPE> GetEffectiveShape( PCB_LAYER_ID aLayer = UNDEFINED_LAYER ) const override;

    const std::shared_ptr<SHAPE_POLY_SET>& GetEffectivePolygon() const;

    const SHAPE_SEGMENT* GetEffectiveHoleShape() const;

    int GetBoundingRadius() const;

    int GetLocalClearanceOverrides( wxString* aSource ) const override;

    int GetSolderMaskMargin() const;

    wxSize GetSolderPasteMargin() const;

    void SetZoneConnection( ZONE_CONNECTION aType ) { m_zoneConnection = aType; }
    ZONE_CONNECTION GetZoneConnection() const { return m_zoneConnection; }

    ZONE_CONNECTION GetEffectiveZoneConnection( wxString* aSource = nullptr ) const;

    void SetThermalSpokeWidth( int aWidth ) { m_thermalWidth = aWidth; }
    int GetThermalSpokeWidth() const { return m_thermalWidth; }

    int GetEffectiveThermalSpokeWidth( wxString* aSource = nullptr ) const;

    void SetThermalGap( int aGap ) { m_thermalGap = aGap; }
    int GetThermalGap() const { return m_thermalGap; }

    int GetEffectiveThermalGap( wxString* aSource = nullptr ) const;

    void SetRoundRectCornerRadius( double aRadius );
    int GetRoundRectCornerRadius() const;

    wxPoint ShapePos() const;

    void SetRoundRectRadiusRatio( double aRadiusScale );
    double GetRoundRectRadiusRatio() const { return m_roundedCornerScale; }

    void SetChamferRectRatio( double aChamferScale );
    double GetChamferRectRatio() const { return m_chamferScale; }

    void SetChamferPositions( int aPositions ) { m_chamferPositions = aPositions; }
    int GetChamferPositions() const { return m_chamferPositions; }

    int GetSubRatsnest() const                  { return m_subRatsnest; }
    void SetSubRatsnest( int aSubRatsnest )     { m_subRatsnest = aSubRatsnest; }

    void SetRemoveUnconnected( bool aSet )      { m_removeUnconnectedLayer = aSet; }
    bool GetRemoveUnconnected() const           { return m_removeUnconnectedLayer; }

    void SetKeepTopBottom( bool aSet )      { m_keepTopBottomLayer = aSet; }
    bool GetKeepTopBottom() const           { return m_keepTopBottomLayer; }

    void GetMsgPanelInfo( EDA_DRAW_FRAME* aFrame, std::vector<MSG_PANEL_ITEM>& aList ) override;

    bool IsOnLayer( PCB_LAYER_ID aLayer ) const override
    {
        return m_layerMask[aLayer];
    }

    bool FlashLayer( int aLayer ) const;

    bool FlashLayer( LSET aLayers ) const;

    bool HitTest( const wxPoint& aPosition, int aAccuracy = 0 ) const override;
    bool HitTest( const EDA_RECT& aRect, bool aContained, int aAccuracy = 0 ) const override;

    wxString GetClass() const override
    {
        return wxT( "PAD" );
    }

    const EDA_RECT GetBoundingBox() const override;

    void SetDrawCoord();

    //todo: Remove SetLocalCoord along with m_pos
    void SetLocalCoord();

    static int Compare( const PAD* padref, const PAD* padcmp );

    void Move( const wxPoint& aMoveVector ) override
    {
        m_pos += aMoveVector;
        SetLocalCoord();
        SetDirty();
    }

    void Rotate( const wxPoint& aRotCentre, double aAngle ) override;

    wxString GetSelectMenuText( EDA_UNITS aUnits ) const override;

    BITMAPS GetMenuImage() const override;

    wxString ShowPadShape() const;

    wxString ShowPadAttr() const;

    EDA_ITEM* Clone() const override;

    PAD* ClonePad() const
    {
        return (PAD*) Clone();
    }

    void BuildEffectiveShapes( PCB_LAYER_ID aLayer ) const;
    void BuildEffectivePolygon() const;

    virtual void ViewGetLayers( int aLayers[], int& aCount ) const override;

    double ViewGetLOD( int aLayer, KIGFX::VIEW* aView ) const override;

    virtual const BOX2I ViewBBox() const override;

    virtual void SwapData( BOARD_ITEM* aImage ) override;

#if defined(DEBUG)
    virtual void Show( int nestLevel, std::ostream& os ) const override { ShowDummy( os ); }
#endif


private:
    void addPadPrimitivesToPolygon( SHAPE_POLY_SET* aMergedPolygon, int aError,
                                    ERROR_LOC aErrorLoc ) const;

private:
    wxString      m_number;             // Pad name (pin number in schematic)
    wxString      m_pinFunction;        // Pin name in schematic
    wxString      m_pinType;            // Pin electrical type in schematic

    wxPoint       m_pos;                // Pad Position on board

    PAD_SHAPE     m_padShape;           // Shape: PAD_SHAPE::CIRCLE, PAD_SHAPE::RECT,
                                        //   PAD_SHAPE::OVAL, PAD_SHAPE::TRAPEZOID,
                                        //   PAD_SHAPE::ROUNDRECT, PAD_SHAPE_POLYGON
    /*
     * 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>> m_editPrimitives;

    // Must be set to true to force rebuild shapes to draw (after geometry change for instance)
    mutable bool                              m_shapesDirty;
    mutable std::mutex                        m_shapesBuildingLock;
    mutable EDA_RECT                          m_effectiveBoundingBox;
    mutable std::shared_ptr<SHAPE_COMPOUND>   m_effectiveShape;
    mutable std::shared_ptr<SHAPE_SEGMENT>    m_effectiveHoleShape;

    mutable bool                              m_polyDirty;
    mutable std::mutex                        m_polyBuildingLock;
    mutable std::shared_ptr<SHAPE_POLY_SET>   m_effectivePolygon;
    mutable int                               m_effectiveBoundingRadius;

    /*
     * How to build the custom shape in zone, to create the clearance area:
     * CUST_PAD_SHAPE_IN_ZONE_OUTLINE = use pad shape
     * CUST_PAD_SHAPE_IN_ZONE_CONVEXHULL = use the convex hull of the pad shape
     */
    CUST_PAD_SHAPE_IN_ZONE  m_customShapeClearanceArea;

    int               m_subRatsnest;        // Variable used to handle subnet (block) number in
                                            //   ratsnest computations

    wxSize            m_drill;              // Drill diameter (x == y) or slot dimensions (x != y)
    wxSize            m_size;               // X and Y size (relative to orient 0)

    PAD_DRILL_SHAPE_T m_drillShape;         // PAD_DRILL_SHAPE_CIRCLE, PAD_DRILL_SHAPE_OBLONG

    double            m_roundedCornerScale; // Scaling factor of min(width, height) to corner
                                            //   radius, default 0.25
    double            m_chamferScale;       // Scaling factor of min(width, height) to chamfer
                                            //   size, default 0.25
    int               m_chamferPositions;   // The positions of the chamfers (at orient 0)

    PAD_SHAPE         m_anchorPadShape;     // For custom shaped pads: shape of pad anchor,
                                            //   PAD_SHAPE::RECT, PAD_SHAPE::CIRCLE

    /*
     * 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.
     */
    wxPoint     m_offset;

    LSET        m_layerMask;        // Bitwise layer: 1 = copper layer, 15 = cmp,
                                    // 2..14 = internal layers, 16..31 = technical layers

    wxSize      m_deltaSize;        // Delta for PAD_SHAPE::TRAPEZOID; half the delta squeezes
                                    //   one end and half expands the other.  It is only valid
                                    //   to have a single axis be non-0.

    wxPoint     m_pos0;             // Initial Pad position (i.e. pad position relative to the
                                    //   footprint anchor, orientation 0)

    PAD_ATTRIB  m_attribute;        // PAD_ATTRIB_NORMAL, PAD_ATTRIB::SMD, PAD_ATTRIB::CONN,
                                    //   PAD_ATTRIB::NPTH
    PAD_PROP    m_property;         // Property in fab files (BGA, FIDUCIAL, TESTPOINT, etc.)

    double      m_orient;           // in 1/10 degrees

    int         m_lengthPadToDie;   // Length net from pad to die, inside the package

    bool        m_removeUnconnectedLayer;

    bool        m_keepTopBottomLayer;

    /*
     * Pad clearances, margins, etc. exist in a hierarchy.  If a given level is specified then
     * the remaining levels are NOT consulted.
     *
     * LEVEL 1: (highest priority) local overrides (pad, footprint, etc.)
     * LEVEL 2: Rules
     * LEVEL 3: Accumulated local settings, netclass settings, & board design settings
     *
     * These are the LEVEL 1 settings for a pad.
     */
    int         m_localClearance;
    int         m_localSolderMaskMargin;        // Local solder mask margin
    int         m_localSolderPasteMargin;       // Local solder paste margin absolute value
    double      m_localSolderPasteMarginRatio;  // Local solder mask margin ratio of pad size
                                                // The final margin is the sum of these 2 values

    ZONE_CONNECTION m_zoneConnection;           // No connection, thermal relief, etc.
    int         m_thermalWidth;                 // Thermal spoke width.
    int         m_thermalGap;
};

#endif  // PAD_H