HSP : HSP3Dish / onion software 2011(c)

# HSP3Dish iOS版プログラミングガイド

1. iOS版 HSP3Dish概要
2. 環境の準備
3. サンプルプロジェクト
4. スクリプトの準備
5. XCode4プロジェクトの作成
6. HSP3Dish関連ファイルの登録
7. HSP3Dishの実行と設定
8. iOS版の注意事項、制限
9. iOS版の更新予定

## iOS版 HSP3Dish概要

iOS版 HSP3Dishは、iOS搭載機種(iPhoneシリーズ,iPadシリーズ,iPod Touch)上で動作するHSP3Dishのランタイムです。 Windows版 HSP3Dishがサポートする機能をiOS上で再現することが可能です。 (iOS版 HSP3Dishは、Windows版のスクリプトを実行させることを目的としており、HSP3開発システムそのものをiOS上で再現するものではありません。)
このマニュアルでは、iOS版の利用方法、注意点などを説明していきます。

## 環境の準備

現状ではiPhone/iPadの実機上で動作させるためには、MacOSX環境及び開発ツールXcode、iOS Developer Program(有償)が必要になります。
ここまでに必要なプロセスは、通常のiPhone/iPadの開発と変わりません。詳しくは、iOS Developer Programのホームページなど各種資料を参照してください。

    	iOS Developer Program
    	http://developer.apple.com/jp/programs/ios/

このドキュメントでは、Xcode4が実際に動作し、iPhone/iPadの実機にプログラムが転送できることを前提として、HSP3Dishの導入方法を解説します。 それまでの準備については、既存のマニュアル等をご覧ください。

## サンプルプロジェクト

アーカイブには、HSP3.3フルセットに含まれているブロック崩しのHSP3Dishサンプル(block3.hsp)を、 Xcode4のプロジェクトに変換したサンプルが含まれています。
「iHSP10」「block」フォルダをOSX上にコピーした後、「block.xcodeproj」を開いてビルドすることで 実際にiOSデバイス上で動作させることができます。

## スクリプトの準備

iOS上でスクリプトを動作させる場合には、最初にWindows上でスクリプトをCソースコードに変換します。 スクリプトエディタの、「ツール」メニューから「指定ファイルをCソースに変換」メニューを選択してください。 ツールの画面が起動するので、block3のスクリプトを指定して「変換」ボタンを押してください。 この時、「出力ソースをUTF-8に変換」のチェックをONにしておくのを忘れないでください。

正常に終了するとスクリプトと同じフォルダに拡張子が.cppのCソースファイルが作成されます。 これでスクリプトの準備は完了です。

## XCode4プロジェクトの作成

OSX上でXcode4を起動して新規プロジェクト(Create a new Xcode project)を選択します。 テンプレートの選択画面になりますので、「iOS Application」の「Window-based Application」を選び「Next」を押してください。

オプション画面で、製品名(Product Name)入力します。
識別子(Company Identifier)は、作成者を識別する名前(メーカー名など)を入力します。
Device FamilyはiPhoneに設定し、2つのチェックボックスは、基本的には外しておいて構いません。

次に、プロジェクトのフォルダを作成する場所を設定します。これは任意の場所を指定して構いません。
正常にプロジェクトが作成されると、開発環境(IDE)が起動します。

## HSP3Dish関連ファイルの登録

作成されたプロジェクトのフォルダと同じ階層に、「iHSP10」フォルダを配置してください。 「iHSP」フォルダはこのアーカイブに同梱されています。

XCode上でプロジェクトに必要なファイルを追加してください。
Fileメニューから、「Add Files to〜」を選択し、「iHSP10」のフォルダ(下層も含む)を追加(Add)します。
さらに、Windows上で作成されたCソースファイル(拡張子が.cppのファイル)を追加(Add)します。

続いて、プロジェクトにフレームワークの追加を行ないます。以下のフレームワークを追加してください。

- AudioToolbox.framework
- OpenAL.framework
- OpenGLES.framework
- QuartzCore.framework

フレームワークの追加は、プロジェクト設定の「Build Phases」タブの「Link Binary With Libraries」項目の「+」ボタンで行なうことができます。
正常に追加されると、ファイルナビゲーターは以下のような状態になります。

必要に応じて、プロジェクトのSupporting Files内にある、[プロジェクト名]-info.plistファイルにフルスクリーンの設定を追加します。

- Localization native development region項目をJapanに設定変更
- Status bar is initally hidden項目を追加し、Yesに設定(フルスクリーンにする場合)

アイコンやデータファイル(画像やサウンド)がある場合は、「resource」フォルダを作成してプロジェクトに追加(Add)してください。

以上で、hsp3dishのビルドを行なう環境が整いました。

## HSP3Dishの実行と設定

実際にHSP3Dishを実行させる場合は、HSPランタイムの初期化コードをAppDelegateに組み込む必要があります。 プロジェクトの作成時に自動的に生成される、[プロジェクト名]AppDelegate.mファイルをエディタで開き編集します。

冒頭の「#import "〜AppDelegate.h"」の下に以下のコードを追加してください。
(「iHSP10」への相対パス指定によりクラス宣言を読み込んでいます)

    	    #import "../../iHSP10/Classes/HspView.h"

次に「- (BOOL)application:〜{」のあるブロックに以下のコードを追加してください。
(HSPの実行を行なうHspViewクラスを生成しウィンドウに設定しています)

    	    //ビューの生成と追加
    	    HspView* view=[[HspView alloc] initWithFrame:CGRectMake(0,0,320,480)];
    	    [view startFrame:60];
    	    [view clsMode:1 color:0xffffff];
    	    [self.window addSubview:view];
    	    [view release];

追加すると、以下のようなコードになります。

HSPランタイムを組み込む追加コードにより、いくつかの設定を行なうことができます。

    	    HspView* view=[[HspView alloc] initWithFrame:CGRectMake(0,0,320,480)];

この設定により、左上(0,0)から(320,480)の範囲を描画フレームとしています。 320×480は、iPhone 3GSの設定に合わせてありますが、iPadなど他の解像度を利用する場合はこの値を変更する必要があります。

    	    [view startFrame:60];

この設定により、タスクが実行されるフレームレートをコントロールすることができます。 通常は、60を指定することにより秒間60フレーム(fps)となっていますが、この値を変更することができます。 通常のHSPとは異なり、iOS版のHSP3Dishでは指定されたフレームレートを単位として実行を行なっています。 高いフレームレートを指定することも可能ですが、CPUにかかる負荷はバッテリー消費に影響がありますので、 できる限り抑えた値にしておくことを推奨しています。

    	    [view clsMode:1 color:0xffffff];

この設定により、「redraw 0」による描画開始時に画面をクリア(消去)するかどうかを変更できます。 デフォルトの設定では、クリアは有効に、背景色は白(0xffffff)が指定されています。
「ClsMode:0」にした場合は画面のクリアは行なわれませんので、自前でクリアする必要があります。 (自前で画面クリアを行なう場合に、重複してクリアすることを避けるためのオプション設定になっています。)
「color:0xffffff」は、クリアする色を指定するもので16進数によりRGBのコードを記述します。

適切に設定を行なった上で、「Run」ボタンでビルド実行を行なってください。 HSP3Dishで作成したスクリプトが実行されるはずです。

## iOS版の注意事項、制限

- 入力可能な情報

タップした座標がmousex,mouseyに反映されます。 またstick命令により、クリック(タップ)のON/OFFを取得可能です。

- 画像フォーマットについて

celload、picload命令などで読み込まれる画像は、以下のフォーマットが使用できます。iOSでは、PNG形式が推奨されます。

- PortableNetworkGraphic(PNG)　.png
- TaggedImageFileFormat(TIFF)　.tiff, .tif
- JointPhotographicExpertsGroup(JPEG)　.jpeg, .jpg
- GraphicInterchangeFormat(GIF)　.gif
- WindowsBitmapFormat(DIB)　.bmp, .BMPf
- Windowsアイコン形式　.ico
- Windowsカーソル　.cur
- XWindowビットマップ　.xbm

- 画像サイズについて

celload、picload命令などで読み込まれる画像が、2^nのサイズ、つまり縦・横のサイズが1,2,4,8,16,32,64,128,256,512であることが推奨されます。正方形である必要はありません。 1024,2048,4096などの大きなサイズの画像は扱えない機種もあるので、推奨されません。

- 再生可能なサウンドファイルについて

拡張子が「.wav」「.mp3」「.caf」「.aac」のファイルに対応しています。 圧縮された音声ファイルについては、mmload命令で読み込んだ時点ですべての波形がメモリに展開されるため、多くの音楽を同時に読み込むことは推奨されません。 「.wav」「.mp3」については、Windows版のhsp3dishでサポートされている形式です。 「.caf」「.aac」形式は、Mac及びiOSでサポートされている形式です。

- bsave命令について

現在のバージョンではデータの書き出しには対応していません。

## iOS版の更新予定

以下の機能は今後、上から順に高い優先度で追加される予定です。

- bsave命令によるユーザーデータの保存
- iOS上の各種システム情報取得
- HSP3Dishの各種設定を行なう機能の追加(setreq,getreq命令)
- 画面の自動回転サポート
- 機種による画面サイズ動的変更のサポート
- buttonを始めとする配置オブジェクトのサポート
- サウンド再生時のボリュームコントロール
- grotate、gsquare、gradf命令のサポート
- 傾きセンサーの入力情報の取得
- マルチタッチ入力情報の取得
- http接続、ブラウザの呼び出しサポート
- OBAQプラグイン機能のサポート

バージョンアップの告知は、HSPオフィシャルサイトHSPTV!にて行なわれますので、随時ご確認ください。