iOS開發之SceneKit框架--SCNNode.h

1、SCNNode簡介

　　SCNNode是場景圖的結構元素，表示3D坐標空間中的位置和變換，您可以將模型，燈光，相機或其他可顯示內容附加到該元素。也可以對其做動畫。

 

2、相關API簡介

• 初始化方法

//懶加載
+ (instancetype)node;
//geometry附加到節點的幾何體
+ (SCNNode *)nodeWithGeometry:(nullable SCNGeometry *)geometry;

• 管理Node節點的變換

//Node的變換
@property(nonatomic) simd_float4x4 simdTransform API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//Node的位置動畫
@property(nonatomic) simd_float3 simdPosition API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//Node的旋轉動畫
@property(nonatomic) simd_float4 simdRotation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//Node的方向動畫（四元素），表示通過一個旋轉角度達到和歐拉角一樣的狀態
@property(nonatomic) simd_quatf simdOrientation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//Node的方向動畫（歐拉角），表示為俯仰（X軸旋轉），偏航（Y軸旋轉），和滾動角弧度（Z軸旋轉）的順序
@property(nonatomic) simd_float3 simdEulerAngles API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//Node的縮放動畫
@property(nonatomic) simd_float3 simdScale API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//Node的位置、旋轉和縮放的樞軸點。
@property(nonatomic) simd_float4x4 simdPivot API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 管理Node節點的內容

//Node的名字
@property(nonatomic, copy, nullable) NSString *name;

//添加的燈光
@property(nonatomic, retain, nullable) SCNLight *light;

//添加的相機
@property(nonatomic, retain, nullable) SCNCamera *camera;

//添加的幾何體
@property(nonatomic, retain, nullable) SCNGeometry *geometry;

//添加的骨骼
@property(nonatomic, retain, nullable) SCNSkinner *skinner API_AVAILABLE(macos(10.9));

//形態結構貼圖
@property(nonatomic, retain, nullable) SCNMorpher *morpher API_AVAILABLE(macos(10.9));

/*!
定義接收器屬於什么邏輯“類別”。 默認為1)
 
1.從給定光的影響中排除節點（參見SCNLight.categoryBitMask）
2.從渲染過程中包含/排除節點（參見SCNTechnique.h）
3.3.指定在命中測試時要使用的節點（請參閱SCNHitTestOptionCategoryBitMask）
 */
@property(nonatomic) NSUInteger categoryBitMask API_AVAILABLE(macos(10.10));

• 給Node添加約束

//添加Node的約束數組 具體參考SCNConstraint.h類
@property(copy, nullable) NSArray<SCNConstraint *> *constraints API_AVAILABLE(macos(10.9));

• 訪問描述Node

//描述節：返回包含當前事務開始時所有屬性的節點的副本，並應用任何活動動畫
@property(nonatomic, readonly) SCNNode *presentationNode;

//控件的節點是否是最新的動作和動畫，或者暫停節點和其子節點動畫
@property(nonatomic, getter=isPaused) BOOL paused API_AVAILABLE(macos(10.10));

•  修改節點可見度

//是否隱藏
@property(nonatomic, getter=isHidden) BOOL hidden;

//設置透明度0-1
@property(nonatomic) CGFloat opacity;

//渲染順序 默認值為0，值越大越最后呈現
@property(nonatomic) NSInteger renderingOrder;

//確定節點是否在陰影貼圖中呈現 Defaults to YES.
@property(nonatomic) BOOL castsShadow API_AVAILABLE(macos(10.10));

//在計算光探針時，不捕獲活動節點，固定節點不被探針照亮。可移動節點不被運動模糊。
@property(nonatomic) SCNMovabilityHint movabilityHint API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0));

//enum SCNMovabilityHint
typedef NS_ENUM(NSInteger, SCNMovabilityHint) {
    SCNMovabilityHintFixed, //固定
    SCNMovabilityHintMovable, //可移動
} API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0));

• 管理Node節點的層次結構

//讀取父節點
@property(nonatomic, readonly, nullable) SCNNode *parentNode;

//獲取所有子節點
@property(nonatomic, readonly) NSArray<SCNNode *> *childNodes;

//添加子節點
- (void)addChildNode:(SCNNode *)child;

//添加子節點到數組指定位置
- (void)insertChildNode:(SCNNode *)child atIndex:(NSUInteger)index;

//移除子節點
- (void)removeFromParentNode;

//新節點newChild替換舊節點oldChild
- (void)replaceChildNode:(SCNNode *)oldChild with:(SCNNode *)newChild;

• 搜索節點的層次結構

//name：節點名稱，recursively：是否遞歸方式查詢
//獲取指定的節點樹中的第一個節點
- (nullable SCNNode *)childNodeWithName:(NSString *)name recursively:(BOOL)recursively;

//通過謂詞predicate對子節點進行測試，返回測試通過的所有子節點
- (NSArray<SCNNode *> *)childNodesPassingTest:(NS_NOESCAPE BOOL (^)(SCNNode *child, BOOL *stop))predicate;

//列舉所有子節點
- (void)enumerateChildNodesUsingBlock:(NS_NOESCAPE void (^)(SCNNode *child, BOOL *stop))block API_AVAILABLE(macos(10.10));

//列舉自身節點和所有子節點
- (void)enumerateHierarchyUsingBlock:(NS_NOESCAPE void (^)(SCNNode *node, BOOL *stop))block API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0));

• 自定義節點渲染

//應用於接收器及其子節點的渲染的Core Image過濾器數組。 動畫
//默認為nil。 應該通過在過濾器附加到的每個節點上調用setValue：forKeyPath：來修改過濾器屬性。 如果在將過濾器附加到節點之后直接修改過濾器的輸入，則行為是未定義的
@property(nonatomic, copy, nullable) NSArray<CIFilter *> *filters API_AVAILABLE(macos(10.9)) __WATCHOS_PROHIBITED;

/*
 指定接收器的渲染器委托對象
 
 設置渲染器委托可防止SceneKit渲染器繪制節點，並允許您使用自定義OpenGL代碼
 自定義渲染的首選方法是調整節點幾何的不同材質的材質屬性。 SCNMaterial符合SCNShadable協議，並允許使用GLSL進行更高級的渲染。
 您通常使用具有沒有幾何節點，並且僅用作空間中位置的渲染代理。 例如將粒子系統附加到該節點，並用自定義的OpenGL代碼渲染它。
 */
@property(nonatomic, assign, nullable) id <SCNNodeRendererDelegate> rendererDelegate;

@protocol SCNNodeRendererDelegate <NSObject>
@optional
/**
 當一個節點被渲染時調用。

 @param node 要渲染的節點
 @param renderer 渲染到的場景渲染器
 @param arguments 字典，其值是包裝在NSValue對象中的SCNMatrix4矩陣
 */
- (void)renderNode:(SCNNode *)node renderer:(SCNRenderer *)renderer arguments:(NSDictionary<NSString *, id> *)arguments;
@end

• 添加節點的物理屬性

//節點的物理體的描述
@property(nonatomic, retain, nullable) SCNPhysicsBody *physicsBody API_AVAILABLE(macos(10.10));

//節點的物理場的描述
@property(nonatomic, retain, nullable) SCNPhysicsField *physicsField API_AVAILABLE(macos(10.10));

• 復制節點

/*!
返回接收器的副本。 返回的實例是自動釋放的。
 
復制是遞歸的：每個子節點也將被克隆。 對於非遞歸復制，請改用復制。
復制的節點將與原始實例共享其附加對象（光，幾何，攝像機，...）
如果您想要獨立於原始對象更改副本的材質，則必須單獨復制節點的幾何。*/
- (instancetype)clone;

/*
(平面克隆)
 
返回包含連接節點層次結構中包含的所有幾何的幾何的節點的克隆。
*/
- (instancetype)flattenedClone API_AVAILABLE(macos(10.9));

• 節點的命中測試

/**
 返回接收器子樹中與指定段相交的每個節點的SCNHitTestResult數組

 @param pointA 段相對於接收器的第一點
 @param pointB 段相對於接收器的第二點
 @param options 可選參數（有關可用選項，請參閱SCNSceneRenderer.h中的“命中測試選項”一節）
 @return 有關屏幕空間命中測試方法，請參閱SCNSceneRenderer.h
 */
- (NSArray<SCNHitTestResult *> *)hitTestWithSegmentFromPoint:(SCNVector3)pointA toPoint:(SCNVector3)pointB options:(nullable NSDictionary<NSString *, id> *)options API_AVAILABLE(macos(10.9));

• 執行節點相對操作

//改變節點的方向，使其局部前向矢量指向指定位置。
- (void)simdLookAt:(vector_float3)worldTarget API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//改變節點的方向，使指定的前向矢量指向指定位置。
- (void)simdLookAt:(vector_float3)worldTarget up:(vector_float3)worldUp localFront:(simd_float3)localFront API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//改變節點相對於其當前位置的位置。
- (void)simdLocalTranslateBy:(simd_float3)translation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//改變節點相對於其當前方向的方向。
- (void)simdLocalRotateBy:(simd_quatf)rotation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//通過圍繞場景空間中指定點的旋轉,來改變節點相對於其當前變換的位置和方向。
- (void)simdRotateBy:(simd_quatf)worldRotation aroundTarget:(simd_float3)worldTarget API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 節點相對變換的計算

//表示所有節點在SceneKit中的上、右、前方向
@property(class, readonly, nonatomic) simd_float3 simdLocalUp API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
@property(class, readonly, nonatomic) simd_float3 simdLocalRight API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
@property(class, readonly, nonatomic) simd_float3 simdLocalFront API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//在世界空間中表示相對於節點的上（+Y）、右（+X）、前（-Z）方向向量
@property(readonly, nonatomic) simd_float3 simdWorldUp API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
@property(readonly, nonatomic) simd_float3 simdWorldRight API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
@property(readonly, nonatomic) simd_float3 simdWorldFront API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 管理世界空間中的變換

//接收器在世界空間的位置（相對於場景的根節點）
@property(nonatomic) simd_float3 simdWorldPosition API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//接收器在世界空間的方向（相對於場景的根節點）可動畫
@property(nonatomic) simd_quatf simdWorldOrientation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//接收器在世界空間的變換（相對於場景的根節點）可動
@property(nonatomic) simd_float4x4 simdWorldTransform API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 坐標空間之間的轉換

//將位置從節點的局部坐標空間轉換為另一節點的位置。
- (simd_float3)simdConvertPosition:(simd_float3)position toNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//將位置從另一節點轉換為節點的局部坐標空間。
- (simd_float3)simdConvertPosition:(simd_float3)position fromNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//將方向向量從節點的局部坐標空間轉換為另一節點的方向向量。
- (simd_float3)simdConvertVector:(simd_float3)vector toNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//將方向向量轉換為節點的局部坐標空間與另一節點的方向坐標空間。
- (simd_float3)simdConvertVector:(simd_float3)vector fromNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//將一個變換從節點的局部坐標空間轉換為另一個節點的變換
- (simd_float4x4)simdConvertTransform:(simd_float4x4)transform toNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//將轉換轉換為節點的局部坐標空間，從另一節點轉換為節點的局部坐標空間。
- (simd_float4x4)simdConvertTransform:(simd_float4x4)transform fromNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 處理UI的焦點

//節點的焦點行為。Defaults to SCNNodeFocusBehaviorNone.
@property(nonatomic) SCNNodeFocusBehavior focusBehavior API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
// @enum SCNNodeFocusBehavior
typedef NS_ENUM(NSInteger, SCNNodeFocusBehavior) {
    SCNNodeFocusBehaviorNone = 0,    // 節點是不可聚焦的
    SCNNodeFocusBehaviorOccluding,   // 節點是不可聚焦的，並且防止其視覺上模糊的節點變得可聚焦。
    SCNNodeFocusBehaviorFocusable    // 節點是可聚焦的，並且防止其視覺上模糊的節點變得可聚焦。
} API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 管理節點的變換（SceneKit 類型）

//變換是下面定義的位置，旋轉和刻度的組合。 因此，當設置變換時，接收器的位置，旋轉和縮放比例將更改為匹配新的變換
@property(nonatomic) SCNMatrix4 transform;

//確定接收器在世界空間中的轉換（相對於場景的根節點）。可動畫。
@property(nonatomic, readonly) SCNMatrix4 worldTransform;
- (void)setWorldTransform:(SCNMatrix4)worldTransform API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//確定接收器的位置.動畫)
@property(nonatomic) SCNVector3 position;

//確定接收器在世界空間中的位置（相對於場景的根節點）。
@property(nonatomic) SCNVector3 worldPosition API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//確定接收器的旋轉 可動畫
@property(nonatomic) SCNVector4 rotation;

//確定接收器的方向（四元數） 可動畫
@property(nonatomic) SCNQuaternion orientation API_AVAILABLE(macos(10.10));

//確定接收器在世界空間中的方向（相對於場景的根節點）。
@property(nonatomic) SCNQuaternion worldOrientation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//歐拉角
@property(nonatomic) SCNVector3 eulerAngles API_AVAILABLE(macos(10.10));

//縮放
@property(nonatomic) SCNVector3 scale;

//中心軸
@property(nonatomic) SCNMatrix4 pivot;

• 執行節點相對操作（SceneKit類型） 

//改變節點的方向，使其局部前向矢量指向指定位置。
- (void)lookAt:(SCNVector3)worldTarget API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//改變節點的方向，使指定的前向矢量指向指定位置。
- (void)lookAt:(SCNVector3)worldTarget up:(SCNVector3)worldUp localFront:(SCNVector3)localFront API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//相對於其當前方向改變節點的方向。
- (void)localTranslateBy:(SCNVector3)translation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//相對於其當前位置改變節點的位置。
- (void)localRotateBy:(SCNQuaternion)rotation API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

// 通過圍繞場景空間中指定點的旋轉來改變節點相對於其當前變換的位置和方向。
- (void)rotateBy:(SCNQuaternion)worldRotation aroundTarget:(SCNVector3)worldTarget API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 計算節點相對變換（SceneKit 類型）

/*!
 @property 獲取上方向
 @abstract The local unit Y axis (0, 0, 1).
 */
@property(class, readonly, nonatomic) SCNVector3 localUp API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

/*!
 @property 獲取右方向
 @abstract The local unit X axis (0, 1, 0).
 */
@property(class, readonly, nonatomic) SCNVector3 localRight API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

/*!
 @property 獲取前方向
 @abstract The local unit -Z axis (0, 0, -1).
 */
@property(class, readonly, nonatomic) SCNVector3 localFront API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

/*!
 @property 獲取世界空間上方向
 @abstract The local unit Y axis (0, 0, 1) in world space.
 */
@property(readonly, nonatomic) SCNVector3 worldUp API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

/*!
 @property 獲取世界空間右方向
 @abstract The local unit X axis (0, 1, 0) in world space.
 */
@property(readonly, nonatomic) SCNVector3 worldRight API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

/*!
 @property 獲取世界空間前方向
 @abstract The local unit -Z axis (0, 0, -1) in world space.
 */
@property(readonly, nonatomic) SCNVector3 worldFront API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

• 坐標空間之間的轉換（SceneKit 類型）

//將位置從節點的局部坐標空間轉換為另一節點的位置。
- (SCNVector3)convertPosition:(SCNVector3)position toNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.9));
//將位置從另一節點轉換為節點的局部坐標空間。
- (SCNVector3)convertPosition:(SCNVector3)position fromNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.9));

//將方向向量從節點的局部坐標空間轉換為另一節點的方向向量。
- (SCNVector3)convertVector:(SCNVector3)vector toNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));
//將方向向量轉換為節點的局部坐標空間與另一節點的方向坐標空間
- (SCNVector3)convertVector:(SCNVector3)vector fromNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0));

//將一個變換從節點的局部坐標空間轉換為另一個節點的變換。
- (SCNMatrix4)convertTransform:(SCNMatrix4)transform toNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.9));
//將轉換轉換為節點的局部坐標空間，從另一節點轉換為節點的局部坐標空間。
- (SCNMatrix4)convertTransform:(SCNMatrix4)transform fromNode:(nullable SCNNode *)node API_AVAILABLE(macos(10.9));

•  枚舉

FOUNDATION_EXTERN NSString *const SCNModelTransform;//模型轉換
FOUNDATION_EXTERN NSString *const SCNViewTransform;//視圖轉換
FOUNDATION_EXTERN NSString *const SCNProjectionTransform;//投影轉換
FOUNDATION_EXTERN NSString *const SCNNormalTransform;//正常轉換
FOUNDATION_EXTERN NSString *const SCNModelViewTransform;//正常模型視圖轉換
FOUNDATION_EXTERN NSString *const SCNModelViewProjectionTransform;//模型視圖投影轉換