feat: add ios particle field runtime facade
This commit is contained in:
tei
@@ -0,0 +1,27 @@
|
||||
# STEP-082 iOS Native FieldRuntime Facade 与 XCFramework 发行设计 v1
|
||||
|
||||
状态：IMPLEMENTED / WAITING_MAC_XCFRAMEWORK_VALIDATION
|
||||
|
||||
## 公开边界
|
||||
|
||||
新增 `MLNParticleFieldRuntimeConfiguration`、`MLNParticleFieldRuntime` 和 `MLNMapView (ParticleFieldRuntime)`。公开头只依赖 Foundation 与已有 public Objective-C 前置类型；QBIN 以 `NSData` 传入，不暴露 `mbgl`、STL、Core 指针或 `MLNMapView_Private.h`。
|
||||
|
||||
Configuration 保存 Host-neutral 的 `sourceIdentifier`、`weatherColorLayerIdentifier`、`particleLayerIdentifier`。它不硬编码 RN ID；后续 RN 可继续传 `rn-weather-fields`、`rn-weather-color`、`rn-weather-particles`。
|
||||
|
||||
## 生命周期与 fail-closed
|
||||
|
||||
Runtime 被 `MLNMapView` 的 associated object 持有，Runtime 只弱引用 MapView。replace 先 dispose 并移除旧实例，attach 仅在当前 style 同时存在正确 Core 类型的 `RasterArraySource`、`WeatherColorLayer`、`RasterParticleLayer` 且两个 layer 都引用该 source 时成功。任何不满足条件的 style-ready/source/type/layer 错误都以 `NSError` 返回，不创建 source/layer，不替换 style。
|
||||
|
||||
每条命令重新从 current MapView/current style 查找并验证三对象；不缓存 `RasterArraySource*` 或任何跨 style 生命周期 Core pointer。因此 style reload 后旧 runtime 不会操作悬空对象，而是 fail-closed，Host 应在 style ready 后 replace/attach。
|
||||
|
||||
## V4 转发
|
||||
|
||||
`submitEncodedField` 先守住与 Android 相同的 UTF-8 ID 1..64、contract 1..256 KiB、QBIN 1..64 MiB、generation>0 边界，再调用 Core `parseResolvedFieldProfileContractJson(...)` 和 `RasterArraySource::submitEncodedField(...)`。十个 Core stable result 逐值映射为 ObjC enum；facade 生命周期错误不会伪装成 submit result。
|
||||
|
||||
Color binding 传递 fieldKey、semantic/group、SCALAR/VELOCITY_COMPONENT/DIRECTION_ANGLE 和 expected unit。Particle binding 保留 VECTOR_COMPONENTS 与 DIRECTION_ANGLE，inactive selector 严格为 `(0, 0)`。forecast time/play/pause/speed 和 clear 都只转发给 Core；T0/T1/mix、boundary reuse、QBIN decoder 与 renderer 不在 ObjC 实现重写。
|
||||
|
||||
## 导出与 distribution
|
||||
|
||||
`MLNParticleFieldRuntime.h` 列入 `MLN_IOS_SDK_HEADERS`，由现有 `public_hdrs` 进入 `MapLibre.dynamic`，并由 `Mapbox.h` 导入。`MLNMapView_Private.h` 继续仅列于 private list。
|
||||
|
||||
`release/maplibre-particle/ios/` 建立 module 名不变的 SwiftPM binary template。后续 STEP-083 的链路固定为：`reactTag -> React View Registry -> Fabric ComponentView -> contentView -> MLNMapView -> public MLNParticleFieldRuntime`。当前 peer dependency 是 MLRN 11.3.6；STEP-083 不建立第二个 Map registry、不把 MLRN private header 作为长期 API，并用 `$MLRN_SPM_SPEC` 令 MLRN 与 Bridge 消费同一 MapLibre binary。
|
||||
@@ -0,0 +1,32 @@
|
||||
# STEP-082 iOS Native FieldRuntime Facade 与 XCFramework 发行基线 v1
|
||||
|
||||
状态：IMPLEMENTED / WAITING_MAC_XCFRAMEWORK_VALIDATION
|
||||
|
||||
## 目标与基线
|
||||
|
||||
起始分支 `particle/main`，起始 HEAD `3e03949d3411c830cfff4bf320cd350f5b6a7527`。本 Step 只新增 iOS public V4 facade 和 XCFramework distribution 基线；不重做 STEP-081，也不进入 STEP-083/RN。
|
||||
|
||||
## 执行清单
|
||||
|
||||
- [x] iOS public Native FieldRuntime facade。
|
||||
- [x] MapView-owned replace/current/dispose 生命周期。
|
||||
- [x] V4 submit、binding、forecast、clear 转发。
|
||||
- [x] style reload/source missing fail-closed 与 public header 无 Core/STL 泄漏。
|
||||
- [x] XCFramework public header 构建图接线。
|
||||
- [x] distribution-ready 模板和中文设计文档。
|
||||
- [ ] macOS XCFramework 成功构建、Headers/symbol/zip SHA-256 验证。
|
||||
- [ ] `git diff --check`、scoped commit、push 与最终 HEAD（在实现和文档收尾后执行）。
|
||||
|
||||
## 允许与禁止
|
||||
|
||||
允许修改 iOS public header/implementation、Bazel public export、release 模板以及指定中文文档。禁止改 QBIN V2、FieldProfile、BindingProjection、renderer/Metal physics、STEP-081 smoke、Android/RN/NavSea；本 Step 未修改这些范围。
|
||||
|
||||
## 构建记录与阻塞
|
||||
|
||||
macOS 15.7.7 / Xcode 26.3 / Bazel 8.6.0。已执行 `bazel build //platform/ios:MapLibre.dynamic`；在本 facade 编译前，基线 `//:generated_style_code` 失败：`bazel/core.bzl` 要求 generator 输出 `src/mbgl/style/layers/particle_validation_layer.cpp`，但 `scripts/generate-style-code.mjs` 不生成该文件。该 Core/Bazel codegen 问题不属于本 Step 允许范围，未以扩大修改规避。
|
||||
|
||||
iPhoneOS arm64 CMake `ios-sdk-static` 编译正在以现有 `build-ios` 进行；最终结果必须在完成报告据实更新。未生成 zip，manifest 为 `NOT_BUILT`。
|
||||
|
||||
## 下一步
|
||||
|
||||
先由独立允许范围处理 Bazel style-codegen 基线，随后在相同 commit 重跑 XCFramework 并检查 Headers、public ObjC symbol 和 zip SHA-256。通过前不得写 CLOSED/PASS 或进入 STEP-083。
|
||||
@@ -5,6 +5,7 @@ MLN_IOS_SDK_HEADERS = [
|
||||
"src/MLNCameraChangeReason.h",
|
||||
"src/MLNCompassButton.h",
|
||||
"src/MLNMapProjection.h",
|
||||
"src/MLNParticleFieldRuntime.h",
|
||||
"src/MLNMapView+IBAdditions.h",
|
||||
"src/MLNMapViewDelegate.h",
|
||||
"src/MLNMapView.h",
|
||||
@@ -67,6 +68,7 @@ MLN_IOS_PUBLIC_OBJCPP_SOURCE = [
|
||||
"src/MLNMapProjection.mm",
|
||||
"src/MLNMapView.mm",
|
||||
"src/MLNMapView+Impl.mm",
|
||||
"src/MLNParticleFieldRuntime.mm",
|
||||
"src/MLNScaleBar.mm",
|
||||
"src/UIColor+MLNAdditions.mm",
|
||||
"src/UIImage+MLNAdditions.mm",
|
||||
|
||||
122
platform/ios/src/MLNParticleFieldRuntime.h
Normal file
122
platform/ios/src/MLNParticleFieldRuntime.h
Normal file
@@ -0,0 +1,122 @@
|
||||
#import <Foundation/Foundation.h>
|
||||
|
||||
#import "MLNFoundation.h"
|
||||
#import "MLNMapView.h"
|
||||
|
||||
NS_ASSUME_NONNULL_BEGIN
|
||||
|
||||
FOUNDATION_EXPORT NSErrorDomain const MLNParticleFieldRuntimeErrorDomain;
|
||||
|
||||
typedef NS_ERROR_ENUM(MLNParticleFieldRuntimeErrorDomain, MLNParticleFieldRuntimeErrorCode) {
|
||||
MLNParticleFieldRuntimeErrorInvalidArgument = 1,
|
||||
MLNParticleFieldRuntimeErrorDisposed,
|
||||
MLNParticleFieldRuntimeErrorMapUnavailable,
|
||||
MLNParticleFieldRuntimeErrorStyleNotReady,
|
||||
MLNParticleFieldRuntimeErrorSourceMissing,
|
||||
MLNParticleFieldRuntimeErrorSourceTypeMismatch,
|
||||
MLNParticleFieldRuntimeErrorWeatherColorLayerMissing,
|
||||
MLNParticleFieldRuntimeErrorWeatherColorLayerTypeMismatch,
|
||||
MLNParticleFieldRuntimeErrorParticleLayerMissing,
|
||||
MLNParticleFieldRuntimeErrorParticleLayerTypeMismatch,
|
||||
MLNParticleFieldRuntimeErrorLayerSourceMismatch,
|
||||
};
|
||||
|
||||
typedef NS_ENUM(NSInteger, MLNParticleEncodedFieldSubmitResult) {
|
||||
/// Facade/lifecycle errors are returned through NSError and use no Core result.
|
||||
MLNParticleEncodedFieldSubmitResultNone = 0,
|
||||
MLNParticleEncodedFieldSubmitResultAcceptedInserted = 1,
|
||||
MLNParticleEncodedFieldSubmitResultAcceptedReplacedRevision = 2,
|
||||
MLNParticleEncodedFieldSubmitResultDuplicate = 3,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedDecode = -1,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedContract = -2,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedInvalidFieldKey = -3,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedIdentityConflict = -4,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedStaleRevision = -5,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedIncompatible = -6,
|
||||
MLNParticleEncodedFieldSubmitResultRejectedCapacity = -7,
|
||||
};
|
||||
|
||||
typedef NS_ENUM(NSInteger, MLNParticleFieldValueClass) {
|
||||
MLNParticleFieldValueClassScalar = 0,
|
||||
MLNParticleFieldValueClassVelocityComponent = 1,
|
||||
MLNParticleFieldValueClassDirectionAngle = 2,
|
||||
};
|
||||
|
||||
typedef NS_ENUM(NSInteger, MLNParticleEncodedParticleBindingMode) {
|
||||
MLNParticleEncodedParticleBindingModeVectorComponents = 0,
|
||||
MLNParticleEncodedParticleBindingModeDirectionAngle = 1,
|
||||
};
|
||||
|
||||
/** Host-neutral identifiers for the existing style JSON raster-array and particle layers. */
|
||||
MLN_EXPORT
|
||||
@interface MLNParticleFieldRuntimeConfiguration : NSObject <NSCopying>
|
||||
|
||||
@property (nonatomic, copy, readonly) NSString *sourceIdentifier;
|
||||
@property (nonatomic, copy, readonly) NSString *weatherColorLayerIdentifier;
|
||||
@property (nonatomic, copy, readonly) NSString *particleLayerIdentifier;
|
||||
|
||||
- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier
|
||||
weatherColorLayerIdentifier:(NSString *)weatherColorLayerIdentifier
|
||||
particleLayerIdentifier:(NSString *)particleLayerIdentifier NS_DESIGNATED_INITIALIZER;
|
||||
- (instancetype)init NS_UNAVAILABLE;
|
||||
|
||||
@end
|
||||
|
||||
/**
|
||||
A map-scoped V4 QBIN control facade. It owns neither a provider nor Core field
|
||||
state; each operation resolves the current style again so style reloads fail closed.
|
||||
*/
|
||||
MLN_EXPORT
|
||||
@interface MLNParticleFieldRuntime : NSObject
|
||||
|
||||
@property (nonatomic, copy, readonly) MLNParticleFieldRuntimeConfiguration *configuration;
|
||||
@property (nonatomic, readonly, getter=isDisposed) BOOL disposed;
|
||||
|
||||
- (instancetype)init NS_UNAVAILABLE;
|
||||
- (void)dispose;
|
||||
|
||||
- (MLNParticleEncodedFieldSubmitResult)submitEncodedFieldWithFieldKey:(NSString *)fieldKey
|
||||
fieldID:(NSString *)fieldID
|
||||
generation:(uint64_t)generation
|
||||
dataVersion:(uint64_t)dataVersion
|
||||
contractJSON:(NSString *)contractJSON
|
||||
qbin:(NSData *)qbin
|
||||
error:(NSError * _Nullable * _Nullable)error;
|
||||
|
||||
- (BOOL)setEncodedColorBindingWithFieldKey:(NSString *)fieldKey
|
||||
semanticID:(uint16_t)semanticID
|
||||
groupID:(uint16_t)groupID
|
||||
expectedValueClass:(MLNParticleFieldValueClass)expectedValueClass
|
||||
expectedUnitID:(uint16_t)expectedUnitID
|
||||
error:(NSError * _Nullable * _Nullable)error;
|
||||
|
||||
- (BOOL)setEncodedParticleBindingWithFieldKey:(NSString *)fieldKey
|
||||
mode:(MLNParticleEncodedParticleBindingMode)mode
|
||||
uSemanticID:(uint16_t)uSemanticID
|
||||
uGroupID:(uint16_t)uGroupID
|
||||
vSemanticID:(uint16_t)vSemanticID
|
||||
vGroupID:(uint16_t)vGroupID
|
||||
directionSemanticID:(uint16_t)directionSemanticID
|
||||
directionGroupID:(uint16_t)directionGroupID
|
||||
expectedUnitID:(uint16_t)expectedUnitID
|
||||
error:(NSError * _Nullable * _Nullable)error;
|
||||
|
||||
- (BOOL)setEncodedForecastTime:(uint64_t)timestamp error:(NSError * _Nullable * _Nullable)error;
|
||||
- (BOOL)setEncodedForecastPlaybackState:(BOOL)playing error:(NSError * _Nullable * _Nullable)error;
|
||||
- (BOOL)setEncodedForecastPlaybackSpeed:(float)speed error:(NSError * _Nullable * _Nullable)error;
|
||||
- (BOOL)clearEncodedFieldWithFieldKey:(NSString *)fieldKey error:(NSError * _Nullable * _Nullable)error;
|
||||
- (BOOL)clearAllEncodedFieldsWithError:(NSError * _Nullable * _Nullable)error;
|
||||
|
||||
@end
|
||||
|
||||
/** MapView owns the runtime and disposes a replaced runtime before attaching a new one. */
|
||||
@interface MLNMapView (ParticleFieldRuntime)
|
||||
|
||||
- (nullable MLNParticleFieldRuntime *)replaceParticleFieldRuntimeWithConfiguration:(MLNParticleFieldRuntimeConfiguration *)configuration
|
||||
error:(NSError * _Nullable * _Nullable)error;
|
||||
- (nullable MLNParticleFieldRuntime *)particleFieldRuntime;
|
||||
- (void)disposeParticleFieldRuntime;
|
||||
|
||||
@end
|
||||
|
||||
NS_ASSUME_NONNULL_END
|
||||
253
platform/ios/src/MLNParticleFieldRuntime.mm
Normal file
253
platform/ios/src/MLNParticleFieldRuntime.mm
Normal file
@@ -0,0 +1,253 @@
|
||||
#import "MLNParticleFieldRuntime.h"
|
||||
|
||||
#import "MLNMapView_Private.h"
|
||||
|
||||
#import <objc/runtime.h>
|
||||
|
||||
#include <mbgl/particle/field/field_profile_contract_json.hpp>
|
||||
#include <mbgl/map/map.hpp>
|
||||
#include <mbgl/style/style.hpp>
|
||||
#include <mbgl/style/layers/raster_particle_layer.hpp>
|
||||
#include <mbgl/style/layers/raster_particle_layer_impl.hpp>
|
||||
#include <mbgl/style/layers/weather_color_layer.hpp>
|
||||
#include <mbgl/style/layers/weather_color_layer_impl.hpp>
|
||||
#include <mbgl/style/sources/raster_array_source.hpp>
|
||||
|
||||
#include <cmath>
|
||||
#include <vector>
|
||||
|
||||
NSErrorDomain const MLNParticleFieldRuntimeErrorDomain = @"org.maplibre.MLNParticleFieldRuntime";
|
||||
|
||||
namespace {
|
||||
constexpr NSUInteger MaxEncodedIdentifierUTF8Bytes = 64;
|
||||
constexpr NSUInteger MaxContractUTF8Bytes = 256 * 1024;
|
||||
constexpr NSUInteger MaxQbinBytes = 64 * 1024 * 1024;
|
||||
|
||||
void setError(NSError **error, MLNParticleFieldRuntimeErrorCode code, NSString *description) {
|
||||
if (error) *error = [NSError errorWithDomain:MLNParticleFieldRuntimeErrorDomain
|
||||
code:code
|
||||
userInfo:@{NSLocalizedDescriptionKey: description}];
|
||||
}
|
||||
|
||||
bool hasValidIdentifier(NSString *value) {
|
||||
return value && value.length > 0 && [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding] <= MaxEncodedIdentifierUTF8Bytes;
|
||||
}
|
||||
|
||||
bool hasValidContract(NSString *value) {
|
||||
return value && value.length > 0 && [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding] <= MaxContractUTF8Bytes;
|
||||
}
|
||||
|
||||
std::string stringFromNSString(NSString *value) {
|
||||
const char *utf8 = value.UTF8String;
|
||||
return utf8 ? std::string(utf8) : std::string();
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
@implementation MLNParticleFieldRuntimeConfiguration
|
||||
|
||||
- (instancetype)initWithSourceIdentifier:(NSString *)sourceIdentifier
|
||||
weatherColorLayerIdentifier:(NSString *)weatherColorLayerIdentifier
|
||||
particleLayerIdentifier:(NSString *)particleLayerIdentifier {
|
||||
NSParameterAssert(sourceIdentifier.length > 0);
|
||||
NSParameterAssert(weatherColorLayerIdentifier.length > 0);
|
||||
NSParameterAssert(particleLayerIdentifier.length > 0);
|
||||
if (sourceIdentifier.length == 0 || weatherColorLayerIdentifier.length == 0 || particleLayerIdentifier.length == 0) {
|
||||
[NSException raise:NSInvalidArgumentException format:@"Particle field runtime identifiers must be non-empty."];
|
||||
}
|
||||
if ((self = [super init])) {
|
||||
_sourceIdentifier = [sourceIdentifier copy];
|
||||
_weatherColorLayerIdentifier = [weatherColorLayerIdentifier copy];
|
||||
_particleLayerIdentifier = [particleLayerIdentifier copy];
|
||||
}
|
||||
return self;
|
||||
}
|
||||
|
||||
- (id)copyWithZone:(NSZone *)zone {
|
||||
return [[[self class] allocWithZone:zone] initWithSourceIdentifier:_sourceIdentifier
|
||||
weatherColorLayerIdentifier:_weatherColorLayerIdentifier
|
||||
particleLayerIdentifier:_particleLayerIdentifier];
|
||||
}
|
||||
|
||||
@end
|
||||
|
||||
@interface MLNParticleFieldRuntime () {
|
||||
__weak MLNMapView *_mapView;
|
||||
BOOL _disposed;
|
||||
}
|
||||
- (instancetype)initWithMapView:(MLNMapView *)mapView
|
||||
configuration:(MLNParticleFieldRuntimeConfiguration *)configuration
|
||||
error:(NSError **)error;
|
||||
@end
|
||||
|
||||
@implementation MLNParticleFieldRuntime
|
||||
|
||||
- (instancetype)initWithMapView:(MLNMapView *)mapView
|
||||
configuration:(MLNParticleFieldRuntimeConfiguration *)configuration
|
||||
error:(NSError **)error {
|
||||
if ((self = [super init])) {
|
||||
_mapView = mapView;
|
||||
_configuration = [configuration copy];
|
||||
if (![self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &) { return true; }]) return nil;
|
||||
}
|
||||
return self;
|
||||
}
|
||||
|
||||
- (BOOL)isDisposed { return _disposed; }
|
||||
|
||||
- (void)dispose {
|
||||
_disposed = YES;
|
||||
_mapView = nil;
|
||||
}
|
||||
|
||||
- (BOOL)withCurrentSource:(NSError **)error action:(bool (^)(mbgl::style::RasterArraySource &))action {
|
||||
if (_disposed) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorDisposed, @"Particle field runtime has been disposed.");
|
||||
return NO;
|
||||
}
|
||||
MLNMapView *mapView = _mapView;
|
||||
if (!mapView) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorMapUnavailable, @"The owning map view is no longer available.");
|
||||
return NO;
|
||||
}
|
||||
@try {
|
||||
auto& style = [mapView mbglMap].getStyle();
|
||||
const auto sourceID = stringFromNSString(_configuration.sourceIdentifier);
|
||||
auto *untypedSource = style.getSource(sourceID);
|
||||
auto *source = untypedSource ? untypedSource->as<mbgl::style::RasterArraySource>() : nullptr;
|
||||
if (!source) {
|
||||
setError(error, untypedSource ? MLNParticleFieldRuntimeErrorSourceTypeMismatch : MLNParticleFieldRuntimeErrorSourceMissing,
|
||||
untypedSource ? @"The configured source is not a raster-array source." : @"The configured raster-array source is missing from the current style.");
|
||||
return NO;
|
||||
}
|
||||
const auto weatherID = stringFromNSString(_configuration.weatherColorLayerIdentifier);
|
||||
auto *untypedWeather = style.getLayer(weatherID);
|
||||
auto *weather = untypedWeather && mbgl::style::layerTypeInfoEquals(untypedWeather->getTypeInfo(), mbgl::style::WeatherColorLayer::Impl::staticTypeInfo())
|
||||
? static_cast<mbgl::style::WeatherColorLayer *>(untypedWeather) : nullptr;
|
||||
if (!weather) {
|
||||
setError(error, untypedWeather ? MLNParticleFieldRuntimeErrorWeatherColorLayerTypeMismatch : MLNParticleFieldRuntimeErrorWeatherColorLayerMissing,
|
||||
untypedWeather ? @"The configured weather-color layer has the wrong Core type." : @"The configured weather-color layer is missing from the current style.");
|
||||
return NO;
|
||||
}
|
||||
const auto particleID = stringFromNSString(_configuration.particleLayerIdentifier);
|
||||
auto *untypedParticle = style.getLayer(particleID);
|
||||
auto *particle = untypedParticle && mbgl::style::layerTypeInfoEquals(untypedParticle->getTypeInfo(), mbgl::style::RasterParticleLayer::Impl::staticTypeInfo())
|
||||
? static_cast<mbgl::style::RasterParticleLayer *>(untypedParticle) : nullptr;
|
||||
if (!particle) {
|
||||
setError(error, untypedParticle ? MLNParticleFieldRuntimeErrorParticleLayerTypeMismatch : MLNParticleFieldRuntimeErrorParticleLayerMissing,
|
||||
untypedParticle ? @"The configured raster-particle layer has the wrong Core type." : @"The configured raster-particle layer is missing from the current style.");
|
||||
return NO;
|
||||
}
|
||||
if (weather->getSourceID() != sourceID || particle->getSourceID() != sourceID) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorLayerSourceMismatch, @"Configured particle layers do not reference the configured raster-array source.");
|
||||
return NO;
|
||||
}
|
||||
return action(*source);
|
||||
} @catch (NSException *exception) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorMapUnavailable, exception.reason ?: @"The underlying map is unavailable.");
|
||||
return NO;
|
||||
}
|
||||
}
|
||||
|
||||
- (MLNParticleEncodedFieldSubmitResult)submitEncodedFieldWithFieldKey:(NSString *)fieldKey
|
||||
fieldID:(NSString *)fieldID
|
||||
generation:(uint64_t)generation
|
||||
dataVersion:(uint64_t)dataVersion
|
||||
contractJSON:(NSString *)contractJSON
|
||||
qbin:(NSData *)qbin
|
||||
error:(NSError **)error {
|
||||
if (!hasValidIdentifier(fieldKey) || !hasValidIdentifier(fieldID) || !hasValidContract(contractJSON) || generation == 0 || qbin.length == 0 || qbin.length > MaxQbinBytes) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"Encoded field arguments violate the V4 transport contract.");
|
||||
return MLNParticleEncodedFieldSubmitResultNone;
|
||||
}
|
||||
const auto contract = mbgl::particle::parseResolvedFieldProfileContractJson(stringFromNSString(contractJSON));
|
||||
if (!contract || !hasValidIdentifier([NSString stringWithUTF8String:contract->profileID.c_str()])) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"contractJSON is not a valid V4 field profile contract.");
|
||||
return MLNParticleEncodedFieldSubmitResultNone;
|
||||
}
|
||||
std::vector<uint8_t> bytes(qbin.length);
|
||||
[qbin getBytes:bytes.data() length:bytes.size()];
|
||||
__block MLNParticleEncodedFieldSubmitResult result = MLNParticleEncodedFieldSubmitResultNone;
|
||||
const BOOL completed = [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) {
|
||||
const auto coreResult = source.submitEncodedField(stringFromNSString(fieldKey),
|
||||
{stringFromNSString(fieldID), generation, dataVersion}, *contract, bytes);
|
||||
result = static_cast<MLNParticleEncodedFieldSubmitResult>(coreResult);
|
||||
return true;
|
||||
}];
|
||||
return completed ? result : MLNParticleEncodedFieldSubmitResultNone;
|
||||
}
|
||||
|
||||
- (BOOL)setEncodedColorBindingWithFieldKey:(NSString *)fieldKey semanticID:(uint16_t)semanticID groupID:(uint16_t)groupID expectedValueClass:(MLNParticleFieldValueClass)expectedValueClass expectedUnitID:(uint16_t)expectedUnitID error:(NSError **)error {
|
||||
if (!hasValidIdentifier(fieldKey) || semanticID == 0 || expectedValueClass < MLNParticleFieldValueClassScalar || expectedValueClass > MLNParticleFieldValueClassDirectionAngle) {
|
||||
setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"Invalid encoded color binding."); return NO;
|
||||
}
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) {
|
||||
source.setColorBinding({stringFromNSString(fieldKey), {semanticID, groupID}, static_cast<mbgl::particle::FieldValueClass>(expectedValueClass), expectedUnitID});
|
||||
return true;
|
||||
}];
|
||||
}
|
||||
|
||||
- (BOOL)setEncodedParticleBindingWithFieldKey:(NSString *)fieldKey mode:(MLNParticleEncodedParticleBindingMode)mode uSemanticID:(uint16_t)uSemanticID uGroupID:(uint16_t)uGroupID vSemanticID:(uint16_t)vSemanticID vGroupID:(uint16_t)vGroupID directionSemanticID:(uint16_t)directionSemanticID directionGroupID:(uint16_t)directionGroupID expectedUnitID:(uint16_t)expectedUnitID error:(NSError **)error {
|
||||
if (!hasValidIdentifier(fieldKey)) { setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"Invalid encoded particle field key."); return NO; }
|
||||
const bool vector = mode == MLNParticleEncodedParticleBindingModeVectorComponents && uSemanticID != 0 && vSemanticID != 0 && directionSemanticID == 0 && directionGroupID == 0;
|
||||
const bool direction = mode == MLNParticleEncodedParticleBindingModeDirectionAngle && uSemanticID == 0 && uGroupID == 0 && vSemanticID == 0 && vGroupID == 0 && directionSemanticID != 0;
|
||||
if (!vector && !direction) { setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"Inactive particle selectors must be exactly semanticID = 0 and groupID = 0."); return NO; }
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) {
|
||||
mbgl::particle::ParticleBinding binding;
|
||||
binding.fieldKey = stringFromNSString(fieldKey);
|
||||
binding.expectedUnitID = expectedUnitID;
|
||||
if (vector) { binding.mode = mbgl::particle::ParticleBindingMode::VectorComponents; binding.uPlane = {uSemanticID, uGroupID}; binding.vPlane = {vSemanticID, vGroupID}; }
|
||||
else { binding.mode = mbgl::particle::ParticleBindingMode::DirectionAngle; binding.directionPlane = {directionSemanticID, directionGroupID}; }
|
||||
source.setParticleBinding(std::move(binding));
|
||||
return true;
|
||||
}];
|
||||
}
|
||||
|
||||
- (BOOL)setEncodedForecastTime:(uint64_t)timestamp error:(NSError **)error {
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) { return source.setRequestedForecastTime(timestamp); }];
|
||||
}
|
||||
|
||||
- (BOOL)setEncodedForecastPlaybackState:(BOOL)playing error:(NSError **)error {
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) { source.setForecastPlaybackState(playing ? mbgl::particle::ForecastPlaybackState::Playing : mbgl::particle::ForecastPlaybackState::Paused); return true; }];
|
||||
}
|
||||
|
||||
- (BOOL)setEncodedForecastPlaybackSpeed:(float)speed error:(NSError **)error {
|
||||
if (!std::isfinite(speed) || speed <= 0) { setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"Forecast playback speed must be finite and greater than zero."); return NO; }
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) { return source.setForecastPlaybackSpeed(speed); }];
|
||||
}
|
||||
|
||||
- (BOOL)clearEncodedFieldWithFieldKey:(NSString *)fieldKey error:(NSError **)error {
|
||||
if (!hasValidIdentifier(fieldKey)) { setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"Invalid encoded field key."); return NO; }
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) { return source.clearEncodedField(stringFromNSString(fieldKey)); }];
|
||||
}
|
||||
|
||||
- (BOOL)clearAllEncodedFieldsWithError:(NSError **)error {
|
||||
return [self withCurrentSource:error action:^bool(mbgl::style::RasterArraySource &source) { source.clearAllEncodedFields(); return true; }];
|
||||
}
|
||||
|
||||
@end
|
||||
|
||||
namespace { const void *ParticleFieldRuntimeAssociationKey = &ParticleFieldRuntimeAssociationKey; }
|
||||
|
||||
@implementation MLNMapView (ParticleFieldRuntime)
|
||||
|
||||
- (MLNParticleFieldRuntime *)replaceParticleFieldRuntimeWithConfiguration:(MLNParticleFieldRuntimeConfiguration *)configuration error:(NSError **)error {
|
||||
[self disposeParticleFieldRuntime];
|
||||
if (!configuration) { setError(error, MLNParticleFieldRuntimeErrorInvalidArgument, @"A particle field runtime configuration is required."); return nil; }
|
||||
MLNParticleFieldRuntime *runtime = [[MLNParticleFieldRuntime alloc] initWithMapView:self configuration:configuration error:error];
|
||||
if (!runtime) return nil;
|
||||
objc_setAssociatedObject(self, ParticleFieldRuntimeAssociationKey, runtime, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
|
||||
return runtime;
|
||||
}
|
||||
|
||||
- (MLNParticleFieldRuntime *)particleFieldRuntime {
|
||||
return objc_getAssociatedObject(self, ParticleFieldRuntimeAssociationKey);
|
||||
}
|
||||
|
||||
- (void)disposeParticleFieldRuntime {
|
||||
MLNParticleFieldRuntime *runtime = self.particleFieldRuntime;
|
||||
[runtime dispose];
|
||||
objc_setAssociatedObject(self, ParticleFieldRuntimeAssociationKey, nil, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
|
||||
}
|
||||
|
||||
@end
|
||||
@@ -42,6 +42,7 @@ FOUNDATION_EXPORT MLN_EXPORT const unsigned char MapboxVersionString[];
|
||||
#import "MLNMapView+IBAdditions.h"
|
||||
#import "MLNMapView.h"
|
||||
#import "MLNMapViewDelegate.h"
|
||||
#import "MLNParticleFieldRuntime.h"
|
||||
#import "MLNMultiPoint.h"
|
||||
#import "MLNNetworkConfiguration.h"
|
||||
#import "MLNOfflinePack.h"
|
||||
|
||||
18
release/maplibre-particle/ios/Package.swift.template
Normal file
18
release/maplibre-particle/ios/Package.swift.template
Normal file
@@ -0,0 +1,18 @@
|
||||
// Replace every <...> placeholder only after a reproducible XCFramework zip exists.
|
||||
// The module/product name must remain MapLibre for MLRN compatibility.
|
||||
// swift-tools-version: 5.7
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "MapLibreDistribution",
|
||||
products: [
|
||||
.library(name: "MapLibre", targets: ["MapLibre"]),
|
||||
],
|
||||
targets: [
|
||||
.binaryTarget(
|
||||
name: "MapLibre",
|
||||
url: "<https://example.invalid/maplibre/MapLibre.dynamic.xcframework.zip>",
|
||||
checksum: "<SHA256_OF_REAL_ZIP>"
|
||||
),
|
||||
]
|
||||
)
|
||||
14
release/maplibre-particle/ios/README.md
Normal file
14
release/maplibre-particle/ios/README.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# MapLibre Particle iOS Binary Distribution 基线
|
||||
|
||||
本目录只保存后续独立 distribution repository 所需的可审计模板；不发布二进制、不创建远端仓库，也不改变 MapLibre iOS 上游版本号。
|
||||
|
||||
模块和 product 始终为 `MapLibre`。MLRN 11.3.6 与后续 Particle Bridge 必须通过同一份自定义 MapLibre binary 消费，不能再链接第二个同功能但不同模块名的 framework。
|
||||
|
||||
发布时：
|
||||
|
||||
1. 在 macOS 上从对应 Git commit 成功生成 `MapLibre.dynamic.xcframework`；
|
||||
2. 压缩为 `MapLibre.dynamic.xcframework.zip`，对 zip 计算 SHA-256；
|
||||
3. 用真实 URL、checksum、commit 和构建记录填充 `release-manifest.json`；
|
||||
4. 将相同 URL/checksum 代入 `Package.swift.template`，再在独立 distribution repository 发布。
|
||||
|
||||
外部 binary distribution 版本独立于 `platform/ios/VERSION`；首个建议坐标为 `6.28.0-particle.1`。本 Step 尚未取得可发布 XCFramework zip，因此 manifest 保持 `NOT_BUILT`，不提供伪造 hash。
|
||||
14
release/maplibre-particle/ios/release-manifest.json
Normal file
14
release/maplibre-particle/ios/release-manifest.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"status": "NOT_BUILT",
|
||||
"distributionVersion": "6.28.0-particle.1",
|
||||
"moduleName": "MapLibre",
|
||||
"artifact": {
|
||||
"fileName": "MapLibre.dynamic.xcframework.zip",
|
||||
"url": "NOT_BUILT",
|
||||
"sizeBytes": null,
|
||||
"sha256": "NOT_BUILT"
|
||||
},
|
||||
"sourceCommit": "3e03949d3411c830cfff4bf320cd350f5b6a7527",
|
||||
"notes": "STEP-082 created the template only. Populate artifact fields only from a successful macOS XCFramework build."
|
||||
}
|
||||
@@ -827,3 +827,11 @@ Android V3-08 单次综合验收已完成并关闭。Native `13.4.1-particle.2`
|
||||
- Wind QBIN Golden fixture 范围为 112.5E..157.5E / 0..55.776573N；iOS private smoke 相机调整到约 27.8883N / 135E、zoom 3 后可正常观察。所有 STEP081 临时 readback/固定线/Point fallback 均已清除；错误 Point fallback 的整屏绿色结果未进入正式代码。
|
||||
|
||||
- STEP-081 功能/真机验收提交 `f1c0f92b2b`（`fix: close STEP-081 iOS Metal particle rendering`）已成功 push 到 `origin/particle/main`。
|
||||
|
||||
### 2026-09-18 STEP-082 iOS Native FieldRuntime Facade 与 XCFramework 发行基线
|
||||
|
||||
- 新增 public `MLNParticleFieldRuntimeConfiguration`、`MLNParticleFieldRuntime` 与 `MLNMapView (ParticleFieldRuntime)`；MapView 通过 associated object 持有 runtime，runtime 仅弱引用 MapView，replace 先 dispose 旧实例，dispose 幂等。
|
||||
- facade 每次命令均重新查找 current style 的 `RasterArraySource`、`WeatherColorLayer` 与 `RasterParticleLayer` 并核验真实 Core 类型和 source 关联，不缓存跨 style 生命周期的 Core pointer；style reload、source/layer 缺失均以独立 NSError fail-closed。
|
||||
- V4 入口复用 Core contract parser、decoder/submit、binding、forecast 与 clear；ObjC 层只执行与 Android 一致的 transport guard 和稳定结果映射，未改 QBIN/renderer/Metal、Android、RN 或 NavSea，也未重做 STEP-081。
|
||||
- `MLNParticleFieldRuntime.h` 已加入 iOS Bazel SDK public headers 和 `Mapbox.h`；`MLNMapView_Private.h` 仍仅为 implementation private include。建立 `release/maplibre-particle/ios/` SwiftPM template/manifest，因 XCFramework zip 未生成而明确 `NOT_BUILT`。
|
||||
- macOS Bazel `//platform/ios:MapLibre.dynamic` 在 facade 编译前被既有 style-codegen 输出声明阻断：`particle_validation_layer.cpp` 被列为生成输出但 generator 不生成；未越权改 Core/codegen。iPhoneOS arm64 CMake `ios-sdk-static` 编译已启动，最终状态以 Step/完成报告记录为准；在 XCFramework 成功验证前，STEP-082 保持 `IMPLEMENTED / WAITING_MAC_XCFRAMEWORK_VALIDATION`。
|
||||
|
||||
Reference in New Issue
Block a user