openFrameworksのアドオンを自作する

15476 ワード
openFrameworks openFrameworks テキストリンク

はじめに

openFrameworksのアドオンを作成する手順を示します。
例として、SOILのラッパーを実装します。
アドオン名はofxSOILとしています。

開発環境

openFrameworks v0.10.1
Windows10
VisualStudio2017

雛形をダウンロードする

openframeworks/ofxAddonTemplateから、雛形をダウンロードします。

cd of_v0.10.1_vs2017_release/addons
curl -LOk https://github.com/openframeworks/ofxAddonTemplate/archive/master.zip

解凍して、名前をつけます。

tar -xvf master.zip
rename ofxAddonTemplate-master ofxSOIL
del master.zip

プロジェクトを編集し始める前に、
今の状態をコミットしておきます。

cd ofxSOIL
git init
git add .
git commit -m "最初のコミット"

プロジェクトの説明を書く

最初から入っている README.md はテンプレート自体の説明なので、
これを削除して代わりに README_DEPLOY.md を README.md にします。
また、README_AUTHOR.mdはテンプレートをダウンロードした人向けのものなので、削除します。

del README_AUTHOR.md
del README.md
rename README_DEPLOY.md README.md

README.mdに、プロジェクトの名前やバージョンを記述します。

code README.md

コミットしておきます。

git add .
git commit -m "テンプレートファイルの削除とreadmeの更新"

アドオンが依存するライブラリを設定する

ここでは、SOIL(Simple OpenGL Image Library)をラップしたライブラリを作ってみます。
なので、まずはSOILをビルドします。

cd C:/好きなディレクトリ
git clone https://github.com/kbranigan/Simple-OpenGL-Image-Library
; cmakeを使ってプロジェクトを生成...
; プロジェクトをリリースビルド...

ビルドしたライブラリのソース、ヘッダ、ライブラリファイルをoFが認識できる場所に置く必要があります。
まずはlibsにもとから入っているサンプルフォルダを消します。

cd of_v0.10.1_vs2017_release/addons/ofxSOIL/libs
rd /s necessaryLib

コミットしておきます。

git add .
git commit -m "necessaryLibを削除"

SOILのためのディレクトリを作成します。

mkdir SOIL
mkdir SOIL\src
mkdir SOIL\includes
mkdir SOIL\lib
mkdir SOIL\lib\vs

ディレクトリは現在こうなっています。

C:\Work\of_v0.10.1_vs2017_release\addons\ofxSOIL\libs>tree /f
C:.
└─SOIL
    ├─includes
    ├─lib
    │  └─vs
    └─src

次に、SOILのファイルを全て移動します。
以下のような構造になりました。

C:\Work\of_v0.10.1_vs2017_release\addons\ofxSOIL\libs>tree /f
C:.
└─SOIL
    ├─includes
    │      image_DXT.h
    │      image_helper.h
    │      SOIL.h
    │      stbi_DDS_aug.h
    │      stbi_DDS_aug_c.h
    │      stb_image_aug.h
    │
    ├─lib
    │  └─vs
    │          SOIL.lib
    │
    └─src
            image_DXT.c
            image_DXT.h
            image_helper.c
            image_helper.h
            SOIL.c
            SOIL.h
            stbi_DDS_aug.h
            stbi_DDS_aug_c.h
            stb_image_aug.c
            stb_image_aug.h
            test_SOIL.cpp

コミットしておきます。

git add .
git commit -m "SOILを追加"

addons_config.mk を編集して、oFがライブラリを見つけられるようにします。
また、製作者の名前や配布URLなどもここで記述します。
全てのせると長すぎるので変更箇所のみ載せています。

...

meta:
    ADDON_NAME = ofxSOIL
    ADDON_DESCRIPTION = ofxSOIL is wrapper of SOIL
    ADDON_AUTHOR = @desktopgame
    ADDON_TAGS = "addon"
    ADDON_URL = http://github.com/desktopgame/ofxSOIL

common:
    ...

    # include search paths, this will be usually parsed from the file system
    # but if the addon or addon libraries need special search paths they can be
    # specified here separated by spaces or one per line using +=
    ADDON_INCLUDES += libs/SOIL/includes

    ...

    # source files that will be included as C files explicitly
    ADDON_C_SOURCES += libs/SOIL/src

    ...

vs:
    # After compiling copy the following dynamic libraries to the executable directory
    # only windows visual studio
    # ADDON_DLLS_TO_COPY = 
    ADDON_LIBS += libs/SOIL/lib/vs/soil.lib

    ...

コミットしておきます。

cd ..
git add .
git commit -m "アドオンコンフィグの設定"

また、現在のままだとSOILに元から含まれているテスト用のコードもビルドに含まれてしまいます。
なので、ここでそれを削除しておきます。

del libs\SOIL\src\test_SOIL.cpp
git add .
git commit -m "テストコードを削除"

プログラムを書く

実際にプログラムを書いていきますが、
今のままではただソースコードがおいてあるだけで、IDEのサポートを受けられません。
なので、プロジェクトジェネレータを使って新たにプロジェクトを作成します。
そのプロジェクトから使用するアドオンとして、ofxSOILを参照します。

こうして作成したプロジェクトof_v0.10.1_vs2017_release/apps/myApps/example_TextureLoadを開いていみると、
以下のようにアドオンも含まれていることがわかります。

このとき、アドオンのファイルは新しく作成されたプロジェクトにコピーされているわけではないようです。
なので、このままIDEのサポートを受けながらアドオンのソースコードを編集できますし、
example_TextureLoadプロジェクトを使ってそのままアドオン自体のデバッグも可能です。

※ ここで紹介している方法は私の環境でうまくいく方法というだけで、公式で紹介されている方法ではありません。
他のアドオンを参考にしようとも思いましたが、githubで公開されている他の方のアドオンを見てみてもプロジェクトジェネレータに必要な最低限なファイルしかコミットされていないため、参考にできませんでした。
(たしかに、openFrameworksのクロスプラットフォームであるという特徴を考えると特定のプラットフォームのためのIDEツールが含まれるべきではないと思います。)

ofxMyAddon.hをofxSOIL.hにリネームして、内容を以下のように

#pragma once
#ifndef OFXSOIL_H
#define OFXSOIL_H
#include <string>

struct ofxSOILTexture {
    explicit ofxSOILTexture() = default;

    unsigned char* data;
    int width;
    int height;
    int channel;
};

class ofxSOIL {
public:
    static ofxSOILTexture loadImage(const std::string& filePath);
private:
    ofxSOIL() = delete;
    ~ofxSOIL() = delete;
};
#endif

ofxMyAddon.cppをofxSOIL.cppにリネームして、内容を以下のように

#include "ofxSOIL.h"
#include <SOIL.h>

ofxSOILTexture ofxSOIL::loadImage(const std::string & filePath) {
    ofxSOILTexture tex;
    tex.data = SOIL_load_image(filePath.c_str(), &tex.width, &tex.height, &tex.channel, SOIL_LOAD_AUTO);
    return tex;
}

ofApp.cppの内容を以下のように

...

#include "ofApp.h"
#include "ofxSOIL.h"
#include <iostream>

//--------------------------------------------------------------
void ofApp::setup() {
    ofxSOILTexture tex = ofxSOIL::loadImage("aaa.png");
    std::cout << "w=" << tex.width << " h=" << tex.height << std::endl;
}

...

これでプロジェクトをビルドできるはずです。
アドオンフォルダも変更されています。

git status
git add .
git commit -m "画像読み込み機能を実装"

デモコードをプロジェクトへ追加

さきほど作成したプログラムはあくまでアプリケーション扱いですし、
実際まだmyApps/example_TextureLoadにあると思います。
これをアドオンのディレクトリへ移します。
まずは先にサンプルを削除します。

rd /s example_myFirstExample
rd /s example_mySecondExample

コミットしておきます。

git add .
git commit -m "サンプルを削除"

代わりに、先程作成したプロジェクトをデモコードとしておいておきます。
example_TextureLoadプロジェクトをアドオン直下に移動します。
すると以下のようになるはずです。

C:\Work\of_v0.10.1_vs2017_release\addons\ofxSOIL>tree
C:.
├─docs
├─example_TextureLoad
│  ├─bin
│  │  └─data
│  ├─obj
│  │  └─Win32
│  │      └─Debug
│  │          └─example_.7FD42DF7.tlog
│  └─src
├─libs
│  └─SOIL
│      ├─includes
│      ├─lib
│      │  └─vs
│      └─src
├─scripts
│  └─ci
│      ├─linux
│      └─osx
├─src
└─tests

プロジェクトごとコピーしているので、
このままだとexample_TextureLoadにはVisualStudio固有のプロジェクトデータも残ってしまいます。
気になる人は example_TextureLoad から src bin addons.make を残して他は全て削除してください。

ライセンス

今回のように、アドオンが他のライブラリに依存しているならば
その著作権表示自体もアドオンに含める必要があります。
ただ、SOILはパブリックドメインという著作権が主張されていないプログラムのようです。

自由および不自由なソフトウェアの分類

プロジェクトを公開する前に

howtoより抜粋

> How do I submit my addon to this page?
> You don't have to! Uploading it to github is enough, as long as you have the 'ofx' prefix in your repository name then we'll find it. Feel free to file an issue on github if you want to tell us about it and let us know what category it belongs in.

ofxというプレフィックスのついたプロジェクトは自動的にofxaddons.comに追加される？ようなので
公開するとまずいファイルがないか確認しておくとよいと思います。

プロジェクトを公開する

以下でgithubへ公開されます。

git remote add origin https://github.com/ユーザ名/リポジトリ名
git push origin master

本当なら今回作成したプロジェクト自体をプッシュして実際にofxAddons.comにのるかも確かめたかったのですが、
流石にほとんど中身のないプロジェクトを公開するのは迷惑だと思うので、今回のプロジェクトは公開していません。