一覧に戻る

iOS ネイティブAPIの入力プラグインAPI

2018.07.08iOSネイティブAPI

入力プラグインAPI

このトピックではWikitude SDKネイティブの入力プラグインAPIの概念と制約について説明します。サンプルアプリケーションのソースコードは長くて複雑になるためコード全体は説明せずに、関連するソースコードを抜粋して説明します。入力プラグインAPIは、プラグインAPIを拡張したものなのでプラグインAPIを理解しておくことをお勧めします。

Wikitude SDK 入力プラグインAPIについて

入力プラグインAPIはWikitude SDKネイティブの入力と出力を変更するために使用されます。入力の場合、任意のソースのカスタムフレームデータはWikitude SDK ネイティブAPIの入力処理として供給されます。一方、出力の場合は、Wikitude SDK ネイティブAPIの初期レンダリングの代わりにより高度な実装が可能です。
入力プラグインは、SDKの起動前、またはSDKの実行中に登録できます。Wikitude SDKが起動する前に登録されている場合、内部Wikitudeカメラの実装はまったく開始されず、Wikitude SDKは最初から入力プラグインを使用し始めます。実行時に入力プラグインが登録されている場合、内部Wikitude SDKカメラが最初に停止され、続いて新しく登録された入力プラグインに移行されます。

入力Pluginクラス

class CameraFrameInputPluginModule : public PluginModule {
public:
    CameraFrameInputPluginModule() noexcept = default;
    virtual ~CameraFrameInputPluginModule() = default;

    /** * Override/implement this method to know when the default platform camera is fully released and this camera frame input plugin module can safely access all platform camera resources */
    virtual void onCameraReleased() = 0;
    virtual void onCameraReleaseFailed(const sdk::Error& error_) = 0;

    /** * Default: false */
    bool requestsCameraFrameRendering();

    /* Called from the Wikitude SDK */
    void registerOnPluginCameraReleasedHandler(std::function<void()> onPluginCameraReleasedHandler_);
    void registerNotifyNewUnmanagedCameraFrameHandler(std::function<void(const sdk::CameraFrame& cameraFrame_)> notifyNewUnmanagedCameraFrameHandler_);
    void registerCameraToSurfaceAngleChangedHandler(std::function<void(float cameraToSurfaceAngle_)> cameraToSurfaceAngleChangedHandler_);

protected:
    /** * Call this method to notify a new camera frame to the SDK */
    void notifyNewUnmanagedCameraFrameToSDK(const sdk::CameraFrame& cameraFrame_);

    /** * Call this method to notify the SDK that this camer frame input plugin module fully released all platform camera resources. * */
    void notifyPluginCameraReleased();

    void setCameraToSurfaceAngle(float cameraToSurfaceAngle_);

protected:
    bool                                    _requestsCameraFrameRendering = false;

private:
    std::function<void()>                           _onPluginCameraReleasedHandler;
    std::function<void(const sdk::CameraFrame&)>    _notifyNewUnmanagedCameraFrameHandler;
    std::function<void(float)>                      _cameraToSurfaceAngleChangedHandler;
};

入力プラグインは、単にそれに関連付けられたCameraFrameInputPluginModuleを持つプラグインです。このモジュールは、入力関連機能の実装を可能にします。

入力プラグインモジュールの実装

次のコードは、入力プラグインを作成し、レンダリング処理されるカメラフレームを提供する方法の最小例です。コードは、Wikitude SDKサンプルアプリケーションの単純な入力プラグインサンプルに対応しています。

class SimpleYUVCameraFrameInputPluginModule : public wikitude::sdk::CameraFrameInputPluginModule {
public:
    SimpleYUVCameraFrameInputPluginModule() {
        _requestsCameraFrameRendering = true;
    }

    void onCameraReleased() override {

    }

    void onCameraReleaseFailed(const wikitude::sdk::Error& error_) override {

    }

    void notifyNewCameraFrame(const wikitude::sdk::CameraFrame& cameraFrame_) {
        notifyNewUnmanagedCameraFrameToSDK(cameraFrame_);
    }
};

_requestsCameraFrameRenderingフラグはフレームがSDKによってレンダリングされるべきかどうかを伝えるのに使用されます。
onCameraReleased関数とonCameraReleaseFailed関数は新しいカメラを開く前にSDKの内部カメラがシャットダウンするのを待つために使用します。これは、SDKの起動後に入力プラグインが登録されている場合にのみ適用されます。
notifyNewUnmanagedCameraFrameToSDK関数は、レンダリングと処理のためにSDKにカメラフレームを渡すために使用されます。CameraFrameクラスは、フレームデータとフレームメタデータをカプセル化します。次のサンプルコードは、そのようなオブジェクトを作成する方法を示しています。
カメラフレームを取得した後は、以下のスニペットに近いコードを使用して変換して転送することができます。

const float fov = _fov;
const wikitude::sdk::Size<int> size{_width, _height};
const std::int32_t timescale = presentationTimestamp.timescale;
wikitude::sdk::ColorCameraFrameMetadata metaData(fov, size, wikitude::sdk::CameraPosition::Back, wikitude::sdk::ColorSpace::YUV_420_NV21, timescale );

std::vector<wikitude::sdk::CameraFramePlane> planes;

wikitude::sdk::CameraFramePlane plane(&_frameData[0], static_cast<unsigned int>(frameDataSize));
planes.push_back(plane);

wikitude::sdk::CameraFrame cameraFrame(_frameId++, timevalue, metaData, planes);

static_cast<SimpleYUVCameraFrameInputPluginModule*>(_plugin->getCameraFrameInputPluginModule())->notifyNewCameraFrame(cameraFrame);

特定の高度なユースケースの入力プラグインを実装するには、カスタムカメラのサンプルアプリケーションのソースコードを確認してください。カスタムカメラのサンプルソースコードは、独自の実装をするのに参考になります。