BTimeSource

Constructor

BTimeSource()

protected:

	BTimeSource()

　標準的なBTimeSourceのコンストラクタです。あなたは決して直接BTimeSourceのインスタンスを生成しないで下さい。その代わりに、BTimeSource（できれば他のBMediaNodeが派生しているクラスも同様に）から派生するnodeクラスを生成し、要求されたようにnodeのインスタンスを生成するためにBMediaRosterを使用して下さい。

Member Functions

BroadcastTimeWarp()

	void BroadcastTimeWarp(bigtime_t atRealTime,       bigtime_t newPerformanceTime)

　（例えばseek処理が生じた時など）時間が突然ジャンプする時には必ず、時間が不連続な方法でジャンプしたことを従属する全てのnodeに通知するために、この関数を呼び出して下さい。もしあなたのtime sourceが派生する時間がジャンプするなら、この関数も呼び出して下さい。

　atRealTimeによって指定されるreal timeに、performance timeはnewPerformanceTimeへと即座にジャンプします。

GetStartLatency()

	status_t GetStartLatency(bigtime_t *outLatency)

　outLatencyに、そのtime sourceに従属しているnodeが始動をを行うのに必要な時間を含め、time sourceが始動するのに必要な時間の長さをマイクロ秒単位で返します。

RETURN CODES

B_OK. latencyの値は問題なく返された。

• B_NO_INIT. time sourceが初期化されていない。

GetTime()

	status_t GetTime(bigtime_t *performanceTime, bigtime_t *realTime,       float *drift)

　このtime sourceに対して最も最近発行された時間情報（time information）を返します。この情報は、driftの値と同じく、最後に発行されたタイムスタンプのperformance timeとreal timeを指定します。これは、下記の様により正確なreal timeを与えることによって得られる、現在の真実のperformance timeに手を加えるのに使用できます。

   bigtime_t performanceTime;
   bigtime_t realTime;
   float drift;
   
   while (GetTime(&performanceTime, &realTime, &drift) != B_OK);
   performanceTime = performanceTime + (RealTime() - realTime) * drift;

　しかし、結果として得られたperformanceTimeは、PerformanceTimeFor()を呼び出すことによって得られた値と同じものです。代りにPerformanceTimeFor()を使いましょう。

RETURN CODES

B_OK. 返された情報は正確である。

• その他の値. 返された情報は信頼できない。

HandleMessage()

protected:

	virtual status_t HandleMessage(int32 code, const void *message, size_t size)

　制御ポートから受け取ったメッセージを与えることで、この関数は適切なBTimeSourceのフック関数に、そのメッセージをディスパッチします。もしメッセージがフック関数に合致しなければ、適切なエラーが返されます。

　もしnodeがBTimeSourceから派生しているなら、HandleMessage()は受け継いだ全ての型のHandleMessage()を呼び出すよう実装して下さい。

RETURN CODES

B_OK. メッセージはディスパッチされた。

• その他のエラー. メッセージは、おそらくフック関数に合致しなかったため、ディスパッチできなかった。

IsRunning()

	bool IsRunning(void)

　もしBTimeSourceが現在、時間とともに進行しているならtrueを、停止していればfalseを返します。

Now() , PerformanceTimeFor() , RealTimeFor()

	bigtime_t Now(void) bigtime_t PerformanceTimeFor(bigtime_t realTime) bigtime_t RealTimeFor(bigtime_t performanceTime, bigtime_t withLatency)

　Now()は、現在のperformance timeの近似値を返します。

　PerformanceTimeFor()は、（BTimeSource::RealTime()によって返される）指定されたreal timeによって表されるperformance timeの推定値を返します。

　performance timeを与えられることにより、RealTimeFor()は、与えられたlatencyによって調整され、real timeに対応する近似値を返します。

PublishTime()

protected:

	void PublishTime(bigtime_t performanceTime, bigtime_t realTime, float drift)

　あなたのtime sourceが動作している間、real timeとperformance timeの間のマッピングを絶えずリフレッシュするために、あなたは繰り返しこの関数を呼び出さなければなりません。time sourceが停止している時は、この関数を、全ての引数をゼロにして一度だけ呼び出して下さい。

　引数は以下の意味を持ちます。

• performanceTimeは、正確な現在のperformance timeである。

• realTimeは、現在のreal timeである。

• driftは、real timeと比べてperformance timeが変化する割合を表す値を示す。

　driftの値は、中間の値の挿入を可能にします。例えば、もしビデオソースの再生が普通の速度で行われているとしたら、driftの値は、performance timeとreal timeが同じ比率で進行することを示す1.0となります。

　しかしながら、もしムービーが半分の速度で再生されているとしたら、driftは、0.5となります。これにより、渡されるreal timeのひとつの単位ごとに、performance timeの半分だけが渡されることになります。この情報は、更新が生じた際に毎回time sourceを検索する必要なしに、時間を計算するのに使用されます。

　（driftの値が大きく変化しなければ呼び出す頻度には変化が許されますが、1秒につき約20回呼び出すよう試みるべき）この関数によって提供されるデータは、あなたのnodeから他の世界が見ている情報に過ぎません。

RealTime()

	static bigtime_t RealTime(void)

　全てのtime sourceが自分を計測するのに使用する、現在に於ける絶対的なreal timeを返します。この関数は、この値を得るために唯一信頼できる呼び出しです（Kernel Kitのsystem_time()は使用しないで下さい）。

この時点では、RealTime()及びsystem_time()は同じ値を返します。しかしながら、この関連性を信頼してはいけません。メディアに関する処理をするなら、必ずRealTime()を使用して下さい。

RealTimeFor() see Now()

Seek()

protected:

	virtual void Seek(bigtime_t performanceTime, bigtime_t atRealTime)

　seek要求を扱うために、この関数を実装して下さい。BTimeSourceのperformance timeが調整される際には、BTimeSourceは従属する全てのnodeにその変更を広く伝える必要があります。これを行うには、BroadcastTimeWarp()を呼び出して下さい。

　必ず、少なくともひとつのseek要求を待ち行列に入れて下さい。そうすれば、seek処理を前もって要求しておくことができます。seek要求は、atRealTimeによって指定されるreal timeに生じます。

SendRunMode()

protected:

	void SendRunMode(run_mode mode)

　この関数は、指定されたmodeを、このnodeに従属する全てのnodeに伝達します。これによって、nodeは自分達のtime sourceの実行モードが変更されたことを知ることができます。この関数は、SetRunMode()によって呼び出されます。あなたのBTimeSourceの実装によっては、別の場所でそれを呼び出すことが意味をなしたり、なさなかったりするでしょう。

SetRunMode()

protected:

	virtual void SetRunMode(run_mode mode)

　このフック関数は、誰かがあなたのnodeの実行モードを変更するよう要求した時に呼び出されます。必ず、BMediaNode::SetRunMode()またはBTimeSource::SetRunMode()のいずれかを通して呼び出して下さい。

　modeの取りうる値は下記の通りです :

Constant	Description
BMediaNode::B_FREEWHEELING	もし演奏のタイムラグが起きたり演奏速度が速くなりすぎたとしても、データを正確に保持する。
BMediaNode::B_DECREASE_PRECISION	もし演奏がずれはじめたら、追いつくように試みる。
BMediaNode::B_INCREASE_LATENCY	もし演奏がずれはじめたら、再生の遅延を増やしてバッファの配送頻度を低下させる。
BMediaNode::B_DROP_DATA	もし演奏がずれはじめたら、データをスキップする。

SnoozeUntil()

	virtual void SnoozeUntil(bigtime_t performanceTime, bigtime_t withLatency = 0,       bool retrySignals = false)

　指定された（performance timeで指定された）performanceTimeに、real timeに於て到達するまで待ちます。もしwithLatencyがゼロでなければ、SnoozeUntil()は指定されたperformance timeまで（real timeで）withLatencyマイクロ秒の間待ちます。これによって、なにか処理を開始するまでの間にセットアップする時間を持つことができます。

performanceTimeがperformance timeで指定され、withLatencyがreal timeで指定されるため、あなたはwithLatencyマイクロ秒をperformanceTimeから引くことはできず、その時までsnoozeすることもできません。なぜなら、performanceTimeはreal timeより速いか、または遅いレートで渡されるかも知れないからです（例えば、time sourceが倍速で動作している場合などです）。

　retrySignalsが（デフォルトの）falseである場合、もしperformanceTimeより以前に信号によって割り込まれたなら、SnoozeUntil()はB_INTERRUPTEDを返します。もしretrySignalsがtrueなら、この関数はすぐさまスリープ状態になり、実際にその時間が来るまで返りません。

RETURN CODES

B_OK. エラーなし。snoozeは問題なく完了した。

• B_MEDIA_TIME_SOURCE_STOPPED. time sourceは停止している。停止したtime source上でsnoozeするのは良くないことである。

Start()

protected:

	virtual void Start(bigtime_t realTime)

　この関数は、誰かがBTimeSourceの動作を開始させようと考えた際に呼び出されます。引数realTimeは、time sourceが開始されるreal timeを示します。必要に応じて、要求を待ち行列に入れるようにこの関数を実装して下さい。

　少なくとも一つの開始要求を、必ず待ち行列に入れて下さい。そうすることで、開始要求は前もって書類を提出しておくことが（処理を要求することが）できます。

BTimeSourceはreal timeとperformance timeの間のマッピングを行うために使用されるオブジェクトであるため、開始と停止の時間をperformance timeではなくreal timeで計測します。

Stop()

protected:

	virtual void Stop(bigtime_t realTime)

　Stop()は、誰かがBTimeSourceを停止させようと考えた際に呼び出されます。引数realTimeはtime sourceの動作が停止されるreal timeを示します。この要求を待ち行列に入れるよう、この関数を実装して下さい。

　少なくとも一つの開始要求を、必ず待ち行列に入れて下さい。そうすることで、開始要求は前もって書類を提出しておくことが（処理を要求することが）できます。

BTimeSourceはreal timeとperformance timeの間のマッピングを行うために使用されるオブジェクトであるため、開始と停止の時間をperformance timeではなくreal timeで計測します。

TimeSourceOp()

	virtual status_t TimeSourceOp(const time_source_op_info &op,       void *_reserved = 0)

　この関数は、要求された行動を実行するために、BMediaRoster::Start()、BMediaRoster::Stop()及びBMediaRoster::Seek()関数によって呼び出されます。

　あなたはこれらの要求を処理できるようにこの関数を実装しなければなりません。

　もし要求が問題なく扱われれば、B_OKが返されます。そうでなければ、適切なエラーコードが返されます。

Constants

time_source_op

Declared in: <be/media/TimeSource.h>

Constant	Meaning
B_TIMESOURCE_START	time sourceを開始させる。
B_TIMESOURCE_STOP	time sourceを停止させる。
B_TIMESOURCE_STOP_IMMEDIATELY	time sourceを直ちに停止させる。
B_TIMESOURCE_SEEK	time sourceをseekする。

　これらの定数は、TimeSourceOp()が扱うために呼び出される多様な処理を同定します。

Defined Types

time_source_op_info

Declared in: <be/media/TimeSource.h>

   
   struct time_source_op_info {
      time_source_op op;
      int32 _reserved1;
      bigtime_t real_time;
      bigtime_t performance_time;
      int32 _reserved2[6];
   };

　これは、TimeSourceOp()への要求を記述しています。

• opは、行われる処理を示す。

• real_timeは、要求が満たされるべき時間を示します（これは、BMediaRoster::SeekTimeSource()、StopTimeSource()またはStartTimeSource()関数に渡される引数atRealTimeです）。

• performance_timeは、SeekTimeSource()に渡される引数newPerformanceTimeです。