Rewrote header.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@32780 a95241bf-73f2-0310-859d-f6bbb57e9c96

headers/os/media/MediaEventLooper.h

@@ -1,26 +1,21 @@
-/*******************************************************************************
+/*
-/
+ * Copyright 2009, Haiku, Inc. All rights reserved.
-/	File:			MediaEventLooper.h
+ * Distributed under the terms of the MIT License.
-/
+ */
-/	Description:	BMediaEventLooper spawns a thread which calls WaitForMessage,
+#ifndef _MEDIA_EVENT_LOOPER_H
-/					pushes BMediaNode messages onto its BTimedEventQueues.
-/					informs you when it is time to handle an event.
-/					Report your event latency, push other events onto the queue
-/					and override HandleEvent to do your work.
-/
-/	Copyright 1999, Be Incorporated, All Rights Reserved
-/
-*******************************************************************************/
-
-#if !defined(_MEDIA_EVENT_LOOPER_H)
 #define _MEDIA_EVENT_LOOPER_H
 
+
 #include <MediaNode.h>
 #include <TimedEventQueue.h>
 
-class BMediaEventLooper :
+
-	public virtual BMediaNode
+/*! BMediaEventLooper spawns a thread which calls WaitForMessage, pushes
-{
+	BMediaNode messages onto its BTimedEventQueues. informs you when it
+	is time to handle an event. Report your event latency, push other events
+	onto the queue and override HandleEvent to do your work.
+*/
+class BMediaEventLooper : public virtual BMediaNode {
 protected:
 	enum run_state {
 		B_IN_DISTRESS		= -1,
@@ -33,39 +28,44 @@ class BMediaEventLooper :
 	};
 
 protected:
-		/* this has to be on top rather than bottom to force a vtable in mwcc */
+	explicit					BMediaEventLooper(
+									uint32 apiVersion = B_BEOS_VERSION);
 	virtual						~BMediaEventLooper();
-		explicit			BMediaEventLooper(uint32 apiVersion = B_BEOS_VERSION);
 
-	/* from BMediaNode */		
 protected:
+	// BMediaNode interface
 	virtual	void				NodeRegistered();
-		virtual void		Start(bigtime_t performance_time);
+	virtual	void				Start(bigtime_t performanceTime);
-		virtual void		Stop(bigtime_t performance_time, bool immediate);
+	virtual	void				Stop(bigtime_t performanceTime,
-		virtual void		Seek(bigtime_t media_time, bigtime_t performance_time);
+									bool immediate);
-		virtual void		TimeWarp(bigtime_t at_real_time, bigtime_t to_performance_time);
+	virtual	void				Seek(bigtime_t mediaTime,
-		virtual status_t	AddTimer(bigtime_t at_performance_time, int32 cookie);
+									bigtime_t performanceTime);
+	virtual	void				TimeWarp(bigtime_t atRealTime,
+									bigtime_t toPerformanceTime);
+	virtual	status_t			AddTimer(bigtime_t atPerformanceTime,
+									int32 cookie);
 	virtual	void 				SetRunMode(run_mode mode);
 
-	/* BMediaEventLooper Hook functions */
 protected:
-		/* you must override to handle your events! */
+	// BMediaEventLooper Hook functions
-		/* you should not call HandleEvent directly */
+
+	// NOTE: You must override this method to handle your events!
+	// You should not call HandleEvent directly.
 	virtual void				HandleEvent(const media_timed_event* event,
 									bigtime_t lateness,
 									bool realTimeEvent = false) = 0;
 
-		/* override to clean up custom events you have added to your queue */
+	// Override this method to properly clean up any custom events you have
+	// added to your event queue.
 	virtual void				CleanUpEvent(const media_timed_event* event);
 
-		/* called from Offline mode to determine the current time of the node */
+	// NOTE: Called in offline mode to determine the current time of the node.
-		/* update your internal information whenever it changes */
+	// Update your internal information whenever it changes.
 	virtual	bigtime_t			OfflineTime();
 
-		/* override only if you know what you are doing! */
+	// NOTE: Override this method only if you know what you are doing!
-		/* otherwise much badness could occur */
+	// The default control loop function waits for messages, pops events
-		/* the actual control loop function: */
+	// off the queue and calls DispatchEvent.
-		/* 	waits for messages, Pops events off the queue and calls DispatchEvent */
 	virtual	void				ControlLoop();
 
 			thread_id			ControlThread();
@@ -80,62 +80,55 @@ class BMediaEventLooper :
 			bigtime_t			BufferDuration() const;
 			bigtime_t			SchedulingLatency() const;
 
-		/* use the priority constants from OS.h */
+	// NOTE: Use the priority constants from OS.h or suggest_thread_priority
-		/* or suggest_thread_priority from scheduler.h */
+	// from scheduler.h. The passed priority will be clamped to be in range 5
-		/* will clamp priorities to be inbetween 5 and 120 */
+	// to 120.
 			status_t			SetPriority(int32 priority);
-
-		/* set the run state */
 			void				SetRunState(run_state state);
-		
-		/* clamps to 0 if latency < 0 */
 			void				SetEventLatency(bigtime_t latency);
-		
-		/* clamps to 0 if duration is < 0 */
 			void				SetBufferDuration(bigtime_t duration);
-
-		/* set the offline time returned in OfflineTime */
 			void				SetOfflineTime(bigtime_t offTime);
 
-		/* spawn and resume the thread - must be called from NodeRegistered */
+	// Spawns and resumes the control thread - must be called from
+	// NodeRegistered().
 			void				Run();
 
-		/* close down the thread - must be called from your destructor */
+	// Quits the control thread - must be called from your destructor.
 			void				Quit();
 
-		/* calls HandleEvent and does BMediaEventLooper event work */
+	// Calls HandleEvent and does BMediaEventLooper event work
 			void				DispatchEvent(const media_timed_event* event,
 									bigtime_t lateness,
 									bool realTimeEvent = false);
 
 private:
-		static int32		_ControlThreadStart(void *arg);
+	static	int32				_ControlThreadStart(void* cookie);
-		static void			_CleanUpEntry(const media_timed_event *event, void *context);
+	static	void				_CleanUpEntry(const media_timed_event* event,
-		void				_DispatchCleanUp(const media_timed_event *event);
+									void* context);
+			void				_DispatchCleanUp(
+									const media_timed_event* event);
 
+private:
 			BTimedEventQueue	fEventQueue;
 			BTimedEventQueue	fRealTimeQueue;
 			thread_id			fControlThread;
 			int32				fCurrentPriority;
 			int32				fSetPriority;
-		volatile int32		fRunState;
+			vint32				fRunState;
 			bigtime_t			fEventLatency;
 			bigtime_t			fSchedulingLatency;
 			bigtime_t			fBufferDuration;
 			bigtime_t			fOfflineTime;
 			uint32				fApiVersion;
 
-	private:
-	/* unimplemented for your protection */
-							BMediaEventLooper(const BMediaEventLooper&);
-							BMediaEventLooper& operator=(const BMediaEventLooper&);
-
 protected:
 	virtual	status_t 	DeleteHook(BMediaNode * node);
 
-	/* fragile base class stuffing */
 private:
-		/* it must be thanksgiving!! lots of stuffing! */
+	// FBC padding and forbidden methods
+								BMediaEventLooper(const BMediaEventLooper&);
+			BMediaEventLooper&	operator=(const BMediaEventLooper&);
+
 	virtual	status_t		 	_Reserved_BMediaEventLooper_0(int32 arg, ...);
 	virtual	status_t 			_Reserved_BMediaEventLooper_1(int32 arg, ...);
 	virtual	status_t 			_Reserved_BMediaEventLooper_2(int32 arg, ...);
@@ -161,9 +154,8 @@ class BMediaEventLooper :
 	virtual	status_t 			_Reserved_BMediaEventLooper_22(int32 arg, ...);
 	virtual	status_t 			_Reserved_BMediaEventLooper_23(int32 arg, ...);
 
-		/* turkey for weeks! */
 	bool						_reserved_bool_[4];
 	uint32						_reserved_BMediaEventLooper_[12];
 };
 
-#endif
+#endif // _MEDIA_EVENT_LOOPER_H