@rafaelaugusto/jolt-native 0.1.0-beta.13 → 0.1.0-beta.15

package/README.md

@@ -6,8 +6,12 @@ Optional NativeScript plugin for `@rafaelaugusto/jolt/native`. Install this pack
 npm install @rafaelaugusto/jolt @rafaelaugusto/jolt-native
 ```
 
-Includes compiled scalar/compound playback, MapKit and SceneKit sinks on iOS, and a MapLibre sink on Android. It does not install MapLibre; the app chooses its SDK version. Reference demo: MapLibre Android 11.8.0, NativeScript 9.1, iOS 26 / Android 16. Minimum NativeScript 8.9; native helper APIs require iOS 13+ / Android API 23+ (the app/runtime or SDK may require newer).
+Includes compiled scalar/compound playback, MapKit and SceneKit pose/light/material sinks on iOS, and a MapLibre sink on Android. It does not install MapLibre; the app chooses its SDK version. Reference demo: MapLibre Android 11.8.0, NativeScript 9.1, iOS 26 / Android 16. Minimum NativeScript 8.9; native helper APIs require iOS 13+ / Android API 23+ (the app/runtime or SDK may require newer).
+
+SceneKit appearance supports light intensity/color and material transparency/solid diffuse/emission colors; textures are rejected. See the [lighting guide](https://jolt.rafaelaugusto.dev/guide/scene-lighting) for interpolation and lifecycle limits.
 
 See the [native properties guide](https://jolt.rafaelaugusto.dev/guide/native-properties) for capabilities, authoring, ownership and execution limits.
 
 Release maintainers: publish this optional package together with compatible core releases (`npm publish` from this directory). Build and pack the core at the repository root. The demo uses local file dependencies and never needs the package published for validation.
+
+SceneKit perspective camera field-of-view bindings use `sceneKitFieldOfView(camera)` from the core `/native` entry. See the [camera guide](https://jolt.rafaelaugusto.dev/guide/scene-camera) for projection, lens ownership and lifecycle limits. Available since beta.15. Install matching core/native versions and rebuild the native app to include this adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafaelaugusto/jolt-native",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.15",
   "description": "Optional compiled property adapters for Jolt (MapKit, MapLibre and SceneKit).",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@rafaelaugusto/jolt": ">=0.1.0-beta.13",
+    "@rafaelaugusto/jolt": ">=0.1.0-beta.15",
     "@nativescript/core": ">=8.9.0"
   },
   "nativescript": {

package/platforms/ios/src/JoltReferenceProperties.h

@@ -4,5 +4,17 @@ NS_ASSUME_NONNULL_BEGIN
 + (JoltPropertySink *)mapCoordinate:(NSObject *)annotation;
 + (JoltPropertySink *)mapCamera:(NSObject *)mapView;
 + (JoltPropertySink *)scenePose:(NSObject *)node;
++ (JoltPropertySink *)sceneFieldOfView:(NSObject *)camera;
+/** Diagnostic counts for camera FOV sinks and writes; native camera targets are weak. */
++ (NSUInteger)sceneCameraSinkCount;
++ (NSUInteger)sceneCameraWriteCount;
++ (JoltPropertySink *)sceneLightIntensity:(NSObject *)light;
++ (JoltPropertySink *)sceneLightColor:(NSObject *)light;
++ (JoltPropertySink *)sceneMaterialTransparency:(NSObject *)material;
++ (JoltPropertySink *)sceneMaterialDiffuse:(NSObject *)material;
++ (JoltPropertySink *)sceneMaterialEmission:(NSObject *)material;
+/** Diagnostic count of undisposed appearance sinks (native targets are weak). */
++ (NSUInteger)sceneAppearanceSinkCount;
++ (NSUInteger)sceneAppearanceWriteCount;
 @end
 NS_ASSUME_NONNULL_END

package/platforms/ios/src/JoltReferenceProperties.m

@@ -1,6 +1,7 @@
 #import "JoltReferenceProperties.h"
 #import <MapKit/MapKit.h>
 #import <SceneKit/SceneKit.h>
+#import <UIKit/UIKit.h>
 
 static double longitude(double value) { return fmod(fmod(value+180,360)+360,360)-180; }
 @interface JoltMapCoordinateSink : JoltPropertySink @end
@@ -47,7 +48,183 @@ static double longitude(double value) { return fmod(fmod(value+180,360)+360,360)
     [SCNTransaction commit];
 }
 @end
+// A standalone SCNCamera has no presentation getter. Read its current model FOV,
+// and make each Jolt write immediate, just as for the appearance adapters below.
+static NSUInteger cameraSinks, cameraWrites;
+static BOOL validFieldOfView(double value) { return isfinite(value) && value >= 1 && value <= 179; }
+static BOOL automaticPerspective(SCNCamera *camera) {
+    if (!camera || camera.usesOrthographicProjection || !validFieldOfView(camera.fieldOfView)) return NO;
+    if (camera.projectionDirection != SCNCameraProjectionDirectionVertical && camera.projectionDirection != SCNCameraProjectionDirectionHorizontal) return NO;
+    // A custom projectionTransform ignores viewport size. Inspect two projections
+    // through the public API without mutating the target or allocating a second camera.
+    // Checking only one matrix would accept a custom matrix equal to that viewport's
+    // automatic projection, which a fieldOfView write would silently replace.
+    SCNMatrix4 square = [camera projectionTransformWithViewportSize:CGSizeMake(100, 100)];
+    SCNMatrix4 wide = [camera projectionTransformWithViewportSize:CGSizeMake(200, 100)];
+    return isfinite(square.m11) && isfinite(square.m22) && isfinite(wide.m11) && isfinite(wide.m22)
+        && square.m11 > 0 && square.m22 > 0 && !SCNMatrix4EqualToMatrix4(square, wide);
+}
+@interface JoltSceneCameraSink : JoltPropertySink
+@property(nonatomic) BOOL released;
++ (instancetype)camera:(NSObject *)target;
+@end
+@implementation JoltSceneCameraSink
++ (instancetype)camera:(NSObject *)target {
+    NSParameterAssert(NSThread.isMainThread);
+    if (![target isKindOfClass:SCNCamera.class])
+        [NSException raise:NSInvalidArgumentException format:@"Jolt field of view requires an SCNCamera, not its SCNNode"];
+    if (!automaticPerspective((SCNCamera *)target))
+        [NSException raise:NSInvalidArgumentException format:@"Jolt field of view requires an automatic perspective camera with an angle in 1..179 degrees; orthographic and custom projection matrices are unsupported"];
+    JoltSceneCameraSink *sink = [[self alloc] initWithTarget:target dimensions:1];
+    cameraSinks++;
+    return sink;
+}
+- (BOOL)alive { return automaticPerspective((SCNCamera *)self.target); }
+- (NSArray<NSNumber *> *)read {
+    NSParameterAssert(NSThread.isMainThread);
+    if (!self.alive) [NSException raise:NSInvalidArgumentException format:@"Jolt camera is no longer a supported perspective target"];
+    return @[@([(SCNCamera *)self.target fieldOfView])];
+}
+- (void)write:(NSArray<NSNumber *> *)values {
+    NSParameterAssert(NSThread.isMainThread);
+    if (!self.alive) [NSException raise:NSInvalidArgumentException format:@"Jolt will not overwrite an unsupported camera projection"];
+    if (values.count != 1 || !validFieldOfView(values[0].doubleValue))
+        [NSException raise:NSInvalidArgumentException format:@"Jolt field of view needs one finite angle in 1..179 degrees"];
+    [SCNTransaction begin]; [SCNTransaction setDisableActions:YES];
+    @try {
+        [(SCNCamera *)self.target setFieldOfView:values[0].doubleValue];
+        cameraWrites++;
+    } @finally { [SCNTransaction commit]; }
+}
+- (void)dispose {
+    if (!self.released) { self.released = YES; cameraSinks--; }
+    [super dispose];
+}
+- (void)dealloc { if (!self.released) cameraSinks--; }
+@end
+
+// Appearance is read from the model: SceneKit exposes presentationNode, but no public
+// presentation object for a standalone SCNLight/SCNMaterial. Our immediate writes keep
+// the model current. Apps must remove competing animations before transferring control.
+typedef NS_ENUM(NSUInteger, JoltSceneAppearanceKind) {
+    JoltSceneIntensity, JoltSceneLightColor, JoltSceneTransparency, JoltSceneDiffuse, JoltSceneEmission
+};
+static NSUInteger appearanceSinks, appearanceWrites;
+static CGFloat unitComponent(CGFloat value) { return MAX(0, MIN(1, value)); }
+static CGColorRef copySceneColor(id value) CF_RETURNS_RETAINED {
+    CGColorRef original = NULL;
+    if ([value isKindOfClass:UIColor.class])
+        original = [[value resolvedColorWithTraitCollection:UITraitCollection.currentTraitCollection] CGColor];
+    else if (value && CFGetTypeID((__bridge CFTypeRef)value) == CGColorGetTypeID())
+        original = (__bridge CGColorRef)value;
+    if (!original) return NULL;
+    CGColorSpaceRef space = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+    CGColorRef converted = CGColorCreateCopyByMatchingToColorSpace(space, kCGRenderingIntentDefault, original, NULL);
+    CGColorSpaceRelease(space);
+    if (converted && (CGColorGetNumberOfComponents(converted) != 4 || CGColorSpaceGetModel(CGColorGetColorSpace(converted)) != kCGColorSpaceModelRGB)) {
+        CGColorRelease(converted); return NULL;
+    }
+    return converted;
+}
+@interface JoltSceneAppearanceSink : JoltPropertySink
+@property(nonatomic) JoltSceneAppearanceKind kind;
+@property(nonatomic) BOOL released;
++ (instancetype)target:(NSObject *)target kind:(JoltSceneAppearanceKind)kind;
+@end
+@implementation JoltSceneAppearanceSink
++ (instancetype)target:(NSObject *)target kind:(JoltSceneAppearanceKind)kind {
+    NSParameterAssert(NSThread.isMainThread);
+    BOOL light = kind == JoltSceneIntensity || kind == JoltSceneLightColor;
+    if (![target isKindOfClass:light ? SCNLight.class : SCNMaterial.class])
+        [NSException raise:NSInvalidArgumentException format:@"Jolt SceneKit adapter requires %@", light ? @"SCNLight" : @"SCNMaterial"];
+    JoltSceneAppearanceSink *sink = [[self alloc] initWithTarget:target dimensions:(kind == JoltSceneIntensity || kind == JoltSceneTransparency) ? 1 : 4];
+    sink.kind = kind; appearanceSinks++;
+    if (!sink.alive) {
+        [sink dispose];
+        [NSException raise:NSInvalidArgumentException format:@"Jolt SceneKit adapter requires a valid scalar or solid UIColor/CGColor; textures, images, numbers, patterns and nil color contents are unsupported"];
+    }
+    return sink;
+}
+- (id)contents {
+    switch (self.kind) {
+        case JoltSceneLightColor: return [(SCNLight *)self.target color];
+        case JoltSceneDiffuse: return [(SCNMaterial *)self.target diffuse].contents;
+        case JoltSceneEmission: return [(SCNMaterial *)self.target emission].contents;
+        default: return nil;
+    }
+}
+- (BOOL)alive {
+    if (!self.target) return NO;
+    if (self.kind == JoltSceneIntensity || self.kind == JoltSceneTransparency) {
+        double value = self.kind == JoltSceneIntensity ? [(SCNLight *)self.target intensity] : [(SCNMaterial *)self.target transparency];
+        return isfinite(value) && value >= 0 && (self.kind != JoltSceneTransparency || value <= 1);
+    }
+    CGColorRef color = copySceneColor(self.contents);
+    BOOL valid = color != NULL;
+    if (color) CGColorRelease(color);
+    return valid;
+}
+- (NSArray<NSNumber *> *)read {
+    NSParameterAssert(NSThread.isMainThread);
+    if (!self.alive) [NSException raise:NSInvalidArgumentException format:@"Jolt SceneKit target or solid color contents are no longer valid"];
+    if (self.kind == JoltSceneIntensity) return @[@([(SCNLight *)self.target intensity])];
+    if (self.kind == JoltSceneTransparency) return @[@([(SCNMaterial *)self.target transparency])];
+    CGColorRef color = copySceneColor(self.contents);
+    const CGFloat *v = CGColorGetComponents(color);
+    CGFloat a = unitComponent(v[3]);
+    NSArray *result = @[@(unitComponent(v[0])*a), @(unitComponent(v[1])*a), @(unitComponent(v[2])*a), @(a)];
+    CGColorRelease(color);
+    return result;
+}
+- (void)write:(NSArray<NSNumber *> *)values {
+    NSParameterAssert(NSThread.isMainThread);
+    if (!self.alive) [NSException raise:NSInvalidArgumentException format:@"Jolt will not overwrite unsupported SceneKit contents"];
+    if (values.count != self.dimensions) [NSException raise:NSInvalidArgumentException format:@"Invalid SceneKit component count"];
+    for (NSNumber *value in values)
+        if (!isfinite(value.doubleValue)) [NSException raise:NSInvalidArgumentException format:@"Nonfinite SceneKit component"];
+    if (self.dimensions == 1 && (values[0].doubleValue < 0 || (self.kind == JoltSceneTransparency && values[0].doubleValue > 1)))
+        [NSException raise:NSInvalidArgumentException format:@"SceneKit scalar is outside its range"];
+    UIColor *color = nil;
+    if (self.dimensions == 4) {
+        double a = values[3].doubleValue;
+        if (a < 0 || a > 1) [NSException raise:NSInvalidArgumentException format:@"Invalid SceneKit alpha"];
+        for (NSUInteger i=0; i<3; i++)
+            if (values[i].doubleValue < 0 || values[i].doubleValue > a + 1e-9)
+                [NSException raise:NSInvalidArgumentException format:@"Invalid premultiplied SceneKit color"];
+        color = [UIColor colorWithRed:a ? unitComponent(values[0].doubleValue/a) : 0
+                               green:a ? unitComponent(values[1].doubleValue/a) : 0
+                                blue:a ? unitComponent(values[2].doubleValue/a) : 0 alpha:a];
+    }
+    [SCNTransaction begin]; [SCNTransaction setDisableActions:YES];
+    @try {
+        switch (self.kind) {
+            case JoltSceneIntensity: [(SCNLight *)self.target setIntensity:values[0].doubleValue]; break;
+            case JoltSceneTransparency: [(SCNMaterial *)self.target setTransparency:values[0].doubleValue]; break;
+            case JoltSceneLightColor: [(SCNLight *)self.target setColor:color]; break;
+            case JoltSceneDiffuse: [(SCNMaterial *)self.target diffuse].contents = color; break;
+            case JoltSceneEmission: [(SCNMaterial *)self.target emission].contents = color; break;
+        }
+        appearanceWrites++;
+    } @finally { [SCNTransaction commit]; }
+}
+- (void)dispose {
+    if (!self.released) { self.released = YES; appearanceSinks--; }
+    [super dispose];
+}
+- (void)dealloc { if (!self.released) appearanceSinks--; }
+@end
+
 @implementation JoltReferenceProperties
++ (JoltPropertySink *)sceneFieldOfView:(NSObject *)camera { return [JoltSceneCameraSink camera:camera]; }
++ (NSUInteger)sceneCameraSinkCount { return cameraSinks; }
++ (NSUInteger)sceneCameraWriteCount { return cameraWrites; }
++ (JoltPropertySink *)sceneLightIntensity:(NSObject *)light { return [JoltSceneAppearanceSink target:light kind:JoltSceneIntensity]; }
++ (JoltPropertySink *)sceneLightColor:(NSObject *)light { return [JoltSceneAppearanceSink target:light kind:JoltSceneLightColor]; }
++ (JoltPropertySink *)sceneMaterialTransparency:(NSObject *)material { return [JoltSceneAppearanceSink target:material kind:JoltSceneTransparency]; }
++ (JoltPropertySink *)sceneMaterialDiffuse:(NSObject *)material { return [JoltSceneAppearanceSink target:material kind:JoltSceneDiffuse]; }
++ (JoltPropertySink *)sceneMaterialEmission:(NSObject *)material { return [JoltSceneAppearanceSink target:material kind:JoltSceneEmission]; }
++ (NSUInteger)sceneAppearanceSinkCount { return appearanceSinks; }
++ (NSUInteger)sceneAppearanceWriteCount { return appearanceWrites; }
 + (JoltPropertySink *)mapCoordinate:(NSObject *)annotation {
     NSParameterAssert([annotation conformsToProtocol:@protocol(MKAnnotation)] && [annotation respondsToSelector:@selector(setCoordinate:)]);
     return [[JoltMapCoordinateSink alloc] initWithTarget:annotation dimensions:2];