SCNScene类

//  SCNScene.h

//  Copyright (c) 2012-2016 Apple Inc. All rights reserved.

#import <Foundation/Foundation.h>

#import <SceneKit/SCNAnimation.h>

#import <SceneKit/SCNSceneSource.h>

#import <SceneKit/SCNMaterialProperty.h>

NS_ASSUME_NONNULL_BEGIN

//声明SCNNode  SCNPhysicsWorld 属于类

@class SCNNode;

@class SCNPhysicsWorld;

@protocol SCNSceneExportDelegate;

/*!

 @typedef(定义)  SCNSceneSourceStatusHandler

 @discussion(探讨)  Signature of a block that will be called repeatedly while the scene is being exported.(签名的block反复调用场景时的出口)

 @param(参数) totalProgress(总进展)  is a floating-point number between 0 and 1. 0 means the loading process has just started and 1 that it is complete. (totalProgress是一个浮点数在0和1之间.0意味着加载过程刚刚开始,1则意味它已加载完成)

 @param error(错误)  Will contain information about the failure if any.(如果有,error 将包含有关的故障信息)

 @param stop Set *stop to YES if you want to abort the operation.(如果你想终止操作,设置 *stop 为YES)

 */

typedef void (^SCNSceneExportProgressHandler)(float totalProgress,NSError * _Nullable error,BOOL *stop);

/*! @group Scene writing options (场景写入选项组)*/

/*! @constant(常量)  SCNSceneExportDestinationURL(场景导出目标URL)

    @abstract(摘要)  Specifies the final destination (as a NSURL) of the scene being exported.(指定要导出场景的最终目标[作为NSURL])

    @discussion(讨论)   The destination URL is required if the scene is exported to a temporary directory and then moved to a final destination. This enables the exported document to get correct relative paths to referenced images.(如果将场景导出到临时目录,然后移动到最终目标,则需要目标网址,这使导出的文档能够获得到引用图像的正确相对路径)

 */

FOUNDATION_EXTERN NSString *const SCNSceneExportDestinationURLAPI_AVAILABLE(macosx(10.9));

/*! @group Scene attributes(场景属性组)

    @abstract(摘要) These keys can be used with the -[SCNScene attributeForKey:] method.(这些keys可以和 -[SCNScene attributeForKey]方法一起使用)

 */

#if defined(SWIFT_SDK_OVERLAY2_SCENEKIT_EPOCH) && SWIFT_SDK_OVERLAY2_SCENEKIT_EPOCH >=3

 //定义             场景属性

typedef NSString * SCNSceneAttribute NS_STRING_ENUM;

#else

typedef NSString * SCNSceneAttribute;

#endif

FOUNDATION_EXTERN SCNSceneAttribute const SCNSceneStartTimeAttributeKey;                          

// A floating point value, encapsulated in a NSNumber, containing the start time of the scene.(一个浮点值,封装在NSNumber中,包含场景的开始时间)

FOUNDATION_EXTERN SCNSceneAttribute const SCNSceneEndTimeAttributeKey;                            

// A floating point value, encapsulated in a NSNumber, containing the end time of the scene.(一个浮点值,封装在NSNumber中,包含场景的结束时间)

FOUNDATION_EXTERN SCNSceneAttribute const SCNSceneFrameRateAttributeKey;                          

// A floating point value, encapsulated in a NSNumber, containing the framerate of the scene.(一个浮点值,封装在NSNumber中,包含场景的帧速率)

FOUNDATION_EXTERN SCNSceneAttribute const SCNSceneUpAxisAttributeKeyAPI_AVAILABLE(macosx(10.10));

// A vector3 value, encapsulated in a NSValue, containing the up axis of the scene. This is just for information, setting the up axis as no effect.(一个包含x,y,z向量[结构体]值,封装在NSValue中,包含场景的上轴.这仅仅是为了信息,设置上轴没有任何效果)

#define SCNSceneAttributeStartTime SCNSceneStartTimeAttributeKey

#define SCNSceneAttributeEndTime   SCNSceneEndTimeAttributeKey

#define SCNSceneAttributeFrameRate SCNSceneFrameRateAttributeKey

#define SCNSceneAttributeUpAxis    SCNSceneUpAxisAttributeKey

/*!

 @class    SCNScene

 @abstract SCNScene is the class that describes a 3d scene. It encapsulates a node hierarchy.(SCNScene是描述3D场景的类,它封装了一个节点层次结构)

 */

@interface SCNScene :NSObject <NSSecureCoding>

+ (instancetype)scene;

/*! 

 @property(性质) root(根)

 @abstract Specifies the root node of the node hierarchy.(指定节点层次结构的根节点)

 @discussion(探讨) Note that we have only one root node, whereas some file formats might have many nodes at the root of their hierarchies. The root node(s) of the imported files will therefore be children of the SCNScene's root node.(注意,我们只有一个跟节点,而一些文件格式可能有许多节点在他们那层的根节点上.因此,导入文件的根节点将是SCNScene根节点的子节点)

 */

@property(nonatomic,readonly)SCNNode *rootNode;

/*!

 @property physicsWorld(物理世界)

 @abstract Specifies the physics world of the receiver.(指定接收器的物理世界)

 @discussion Every scene automatically creates a physics world object to simulate physics on nodes in the scene. You use this property to access the scene’s global physics properties, such as gravity. To add physics to a particular node, see physicsBody.(每个场景自动创建一个物理世界对象,以模拟场景中节点上的物理现象.你可以使用此属性来访问场景的全局物理属性,例如重力.要向特定节点添加物理现象,请看physicsBody)

 */

@property(nonatomic,readonly)SCNPhysicsWorld *physicsWorldAPI_AVAILABLE(macosx(10.10));

/*!

 @method attributeForKey:

 @abstract Retrieves a scene attribute.(检索场景属性)

 @discussion The available keys are listed in the "Scene attributes" group.(可用的keys罗列在"场景属性"组中)

 @param key An NSString object that specifies the attribute to be read(指定读取的属性是一个NSString对象)

 */

- (nullableid)attributeForKey:(NSString *)key;

/*! 

 @method(方法) setAttribute:forKey:

 @abstract Sets a scene attribute(设置场景属性)

 @discussion The available keys are listed in the "Scene attributes" group.(可用的keys罗列在"场景属性"组中)

 @param attribute(属性)  An object that specifies the value of the attribute to be written.(指定要写入的属性值是一个对象)

 @param key An NSString object that specifies the attribute to be written(指定要写入的属性是一个NSString对象)

 */

- (void)setAttribute:(nullableid)attribute forKey:(NSString *)key;

/*!

 @property background(背景)

 @abstract Specifies the background of the receiver.(指定接收器的背景)

 @discussion The background is rendered before the rest of the scene.(背景在场景渲染之前出现)

             The background can be rendered as a skybox by setting a cube map as described in SCNMaterialProperty.h(通过设置SCNMaterialProperty.h 中描述的多维数据集映射,可以将背景渲染成天空盒)

            Colors are supported starting macOS 10.12 and iOS 10. Prior to that you can use SCNView.backgroundColor.(支持颜色启动macOS 10.12 和iOS 10 .在此之前,你可以使用SCNView.background)

 */

@property(nonatomic,readonly)SCNMaterialProperty *backgroundAPI_AVAILABLE(macosx(10.9));

/*!

 @property lightingEnvironment(灯光坏境)

 @abstract Specifies the receiver's environment for image-based lighting (IBL).基于图像照明的指定接收器(IBL) 

 @discussion The environment should be a cube map as described in SCNMaterialProperty.h(环境应该是SCNMaterialProperty.h中所述的立方体映射)

 */

@property(nonatomic,readonly)SCNMaterialProperty *lightingEnvironmentAPI_AVAILABLE(macosx(10.12), ios(10.0), tvos(10.0));

#pragma mark - Loading(加载)

/*!

 @method sceneNamed:

 @abstract Creates and returns a scene associated with the specified filename.(创建并返回与指定文件名关联的场景)

 @param name The name of the file. The method looks for a file with the specified name in the application’s main bundle.(文件的名称.该方法在应用程序的主包中查找具有指定名称的文件)

 @discussion This method initializes with no options and does not check for errors. The resulting object is not cached.(此方法初始化时没有选项,并且不检查错误.生成的对象不会缓存)

 */

/*

用法:SCNScene *scene = [SCNScene sceneNamed:@"这里一般传入的是模型场景文件的路径"];

*/

+ (nullableinstancetype)sceneNamed:(NSString *)nameAPI_AVAILABLE(macosx(10.9));

/*!

 @method sceneNamed:options:

 @abstract Creates and returns a scene associated with the specified filename.(创建并返回与指定文件名关联的场景)

 @param name The name of the file. The method looks for a file with the specified name in the application’s main bundle.(文件的名称.该方法在应用程序的主包中查找具有指定名称的文件)

 @param directory(目录)  The name of the bundle sub-directory to search into.(要搜索的bundle子目录的名称)

 @param options(选择/设置)  An options dictionary. The relevant keys are documented in the SCNSceneSource class.(选项字典.相关的密钥记录在SCNSceneSource类中)

 @discussion This method initializes with no options and does not check for errors. The resulting object is not cached.(此方法初始化时没有选项,并且不检查错误.生成的对象不会缓存)

 */

+ (nullableinstancetype)sceneNamed:(NSString *)name inDirectory:(nullableNSString *)directory options:(nullableNSDictionary<SCNSceneSourceLoadingOption,id> *)options API_AVAILABLE(macosx(10.10));

/*!

 @method sceneWithURL:options:error:

 @abstract Creates and returns a scene from the specified URL.(在指定的URL上创建和返回一个场景)

 @param url The URL to the 3D file.(这个URL是一个3D文件)

 @param options An options dictionary. The relevant keys are documented in the SCNSceneSource class.(选项字典.相关的密钥记录在SCNSceneSource类中)

 @param error A NSError object passed by reference to get more information about the error when a nil is returned.(通过引用传递的NSError对象在返回nil时获取有关错误的更多信息)

 @discussion This method is here for convenience. It is equivalent to initializing a SCNSceneSource with the specified url and options, and asking it for its scene with the same options.(这里的方法是为了方便.它等效于使用指定的url和options初始化一个SCNSceneSource,并向它的场景请求相同的选项)

 */

+ (nullableinstancetype)sceneWithURL:(NSURL *)url options:(nullableNSDictionary<SCNSceneSourceLoadingOption,id> *)options error:(NSError **)error;

#pragma mark - Writing(写入)

/*!

 @method writeToURL:options:delegate:progressHandler:

 @abstract write the scene to the specified url.

 @param url the destination url to write the scene to.

 @param options A dictionary of options. The valid keys are described in the "Scene writing options" section.

 @param delegate an optional delegate to manage external references such as images.

 @param progressHandler an optional block to handle the progress of the operation.

 @return Returns YES if the operation succeeded, NO otherwise. Errors checking can be done via the "error"parameter of the 'progressHandler'.

 @discussion macOS 10.10 and lower only supports exporting to .dae files.

             Starting macOS 10.11 exporting supports .dae, .scn as well as file all formats supported by Model I/O.

             Starting iOS 10 exporting supports .scn as well as all file formats supported by Model I/O.

----------------------------------------   中英翻译 分割线    ----------------------------------------------------------------------------

 @方法  writeToURL:options:delegate:progressHandler:

 @摘要  通过指定的URL写这个场景

 @参数 url  将场景写入目标URL.

 @参数 options 一个字典选项.有效的key在"场景书写选项"部分中有所描述

 @参数 delegate 一个可选的代理,用于管理外部引用.例如图片

 @参数 progressHandler(进度处理程序) 一个可选的块来处理操作的进度

 @返回  如果操作成功就返回YES,否则就返回NO.错误检查可以通过"progressHandler"的"error"参数来完成.

 @讨论  macOS 10.10 和 更低的版本只支持导出 .DAE 文件.

        开启 macOS 10.11 支持导出 .dae, .scn 以及模型I/O支持的文件所有格式.

        开启 iOS 10 支持导出 .scn 以及模型I/O支持的文件所有格式.

 */

- (BOOL)writeToURL:(NSURL *)url options:(nullableNSDictionary<NSString *,id> *)options delegate:(nullableid <SCNSceneExportDelegate>)delegate progressHandler:(nullableSCNSceneExportProgressHandler)progressHandlerAPI_AVAILABLE(macosx(10.9), ios(10.0), tvos(10.0))API_UNAVAILABLE(watchos);

#pragma mark - Fog(雾/迷雾/浓雾)

/*!

 @property fogStartDistance(开始雾距离)

 @abstract Specifies the receiver's fog start distance. Animatable. Defaults to 0.(开始指定接收器的雾距离.动画.默认为0)

 */

@property(nonatomic)CGFloat fogStartDistanceAPI_AVAILABLE(macosx(10.10));

/*!

 @property fogEndDistance(结束雾距离)

 @abstract Specifies the receiver's fog end distance. Animatable. Defaults to 0.(结束指定接收器的雾距离.动画.默认为0)

 */

@property(nonatomic)CGFloat fogEndDistanceAPI_AVAILABLE(macosx(10.10));

/*!

 @property fogDensityExponent(雾密度指数)

 @abstract Specifies the receiver's fog power exponent. Animatable. Defaults to 1.(指定接收器的雾密度指数.动画.默认为1)

 @discussion Controls the attenuation between the start and end fog distances. 0 means a constant fog, 1 a linear fog and 2 a quadratic fog, but any positive value will work.(控制开始和结束雾距之间的衰减.0表示恒定雾,1表示线性雾,2表示二次雾,但任何正值都将起作用)

 */

@property(nonatomic)CGFloat fogDensityExponentAPI_AVAILABLE(macosx(10.10));

/*!

 @property fogColor(雾颜色)

 @abstract S pecifies the receiver's fog color (NSColor or CGColorRef). Animatable. Defaults to white.(指定接收器的雾颜色[NSColor / CGColorRef].动画.默认为白色)

 @discussion The initial value is a NSColor.(初始值是NSColor)

 */

@property(nonatomic,retain)id fogColorAPI_AVAILABLE(macosx(10.10));

#pragma mark - Pause(暂停)

/*!

 @property paused(暂停)

 @abstract Controls whether or not the scene is paused. Defaults to NO.(控制场景是否已暂停.默认为NO)

 @discussion Pausing a scene will pause animations, actions, particles and physics.(暂停场景将暂停动画,动作,粒子和物理)

 */

@property(nonatomic,getter=isPaused)BOOL paused API_AVAILABLE(macosx(10.10));

@end

API_AVAILABLE(macosx(10.9), ios(10.0), tvos(10.0))API_UNAVAILABLE(watchos)

@protocol SCNSceneExportDelegate <NSObject>

@optional

/*!

 @method writeImage:withSceneDocumentURL:originalImageURL:

 @abstract Invoked on the delegate to write the referenced image and return the destination url.

 @param image The image to write.

 @param documentURL The url where the scene is currently exported to.

 @param originalImageURL The original url for the image. May be nil if the image was not previously loaded from a url.

 @return The delegate must returns the url of the image that was exported or nil if it didn't export any image. If the returned value is nil, the image will be exported to a default destination in a default format.

 @方法 writeImage:withSceneDocumentURL:originalImageURL:

 @摘要 在代理上调用写入引用的图像并返回目标网址

 @param image 这个图片是白色

 @param documentURL(文件URL)  这个URL是场景现在导出的

 @param originalImageURL(原始图片URL)  图像的原始网址.如果图像之前未从网址加载,则可能为nil

 @return 委托必须返回导出的图像网址，如果未导出任何图像，则返回nil。 如果返回的值为nil，则图像将以默认格式导出到默认目标。

 */

- (nullableNSURL *)writeImage:(UIImage *)image withSceneDocumentURL:(NSURL *)documentURL originalImageURL:(nullableNSURL *)originalImageURLAPI_AVAILABLE(macosx(10.9), ios(10.0), tvos(10.0))API_UNAVAILABLE(watchos);

@end

NS_ASSUME_NONNULL_END