* Rewrote header, adjusted source.

+alphabranch


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

headers/os/media/MediaNode.h

@@ -1,24 +1,17 @@
-/*******************************************************************************
+/*
-/
+ * Copyright 2009, Haiku, Inc. All rights reserved.
-/	File:			MediaNode.h
+ * Distributed under the terms of the MIT License.
-/
+ */
-/   Description:  BMediaNode is the indirect base class for all Media Kit participants.
+#ifndef _MEDIA_NODE_H
-/	However, you should use the more specific BBufferConsumer, BBufferProducer
-/	and others rather than BMediaNode directly. It's OK to multiply inherit.
-/
-/	Copyright 1997-98, Be Incorporated, All Rights Reserved
-/
-*******************************************************************************/
-
-
-#if !defined(_MEDIA_NODE_H)
 #define _MEDIA_NODE_H
 
+
 #include <MediaDefs.h>
 #include <Point.h>
 
 #include <new>
 
+
 class BBufferConsumer;
 class BBufferProducer;
 class BControllable;
@@ -28,9 +21,7 @@ class BTimeSource;
 
 
 class media_node {
-
 public:
-
 								media_node();
 								~media_node();
 
@@ -48,42 +39,48 @@ private:
 struct media_input {
 								media_input();
 								~media_input();
+
 			media_node			node;
 			media_source		source;
 			media_destination	destination;
 			media_format		format;
 			char				name[B_MEDIA_NAME_LENGTH];
+
 private:
 			uint32				_reserved_media_input_[4];
 };
 
+
 struct media_output {
 								media_output();
 								~media_output();
+
 			media_node			node;
 			media_source		source;
 			media_destination	destination;
 			media_format		format;
 			char				name[B_MEDIA_NAME_LENGTH];
+
 private:
 			uint32				_reserved_media_output_[4];
 };
 
+
 struct live_node_info {
 								live_node_info();
 								~live_node_info();
+
 			media_node			node;
 			BPoint				hint_point;
 			char				name[B_MEDIA_NAME_LENGTH];
+
 private:
 			char				reserved[160];
 };
 
 
-struct media_request_info
+struct media_request_info {
-{
+			enum what_code {
-	enum what_code
-	{
 				B_SET_VIDEO_CLIPPING_FOR = 1,
 				B_REQUEST_FORMAT_CHANGE,
 				B_SET_OUTPUT_ENABLED,
@@ -91,6 +88,7 @@ struct media_request_info
 
 				B_FORMAT_CHANGED = 4097
 			};
+
 			what_code			what;
 			int32				change_tag;
 			status_t			status;
@@ -99,19 +97,21 @@ struct media_request_info
 			media_source		source;
 			media_destination	destination;
 			media_format		format;
+
 			uint32				_reserved_[32];
 };
 
-struct media_node_attribute
+
-{
+struct media_node_attribute {
 			enum {
-		B_R40_COMPILED = 1,		//	has this attribute if compiled using R4.0 headers
+				B_R40_COMPILED = 1,
 				B_USER_ATTRIBUTE_NAME = 0x1000000,
 				B_FIRST_USER_ATTRIBUTE
 			};
+
 			uint32				what;
-	uint32		flags;			//	per attribute
+			uint32				flags;
-	int64		data;			//	per attribute
+			int64				data;
 };
 
 
@@ -122,24 +122,32 @@ namespace BPrivate { namespace media {
 } } // BPrivate::media
 
 
-class BMediaNode
+/*!	BMediaNode is the indirect base class for all Media Kit participants.
-{
+	However, you should use the more specific BBufferConsumer, BBufferProducer
+	and others rather than BMediaNode directly. It's OK to multiply inherit.
+*/
+class BMediaNode {
 protected:
-		/* this has to be on top rather than bottom to force a vtable in mwcc */
+	// NOTE: Call Release() to destroy a node.
-virtual	~BMediaNode();	/* should be called through Release() */
+	virtual								~BMediaNode();
-public:
 
+public:
 			enum run_mode {
-			B_OFFLINE = 1,				/* data accurate, no realtime constraint */
+				B_OFFLINE = 1,
-			B_DECREASE_PRECISION,		/* when slipping, try to catch up */
+					// This mode has realtime constraint.
-			B_INCREASE_LATENCY,			/* when slipping, increase playout delay */
+				B_DECREASE_PRECISION,
-			B_DROP_DATA,				/* when slipping, skip data */
+					// When late, try to catch up by reducing quality.
-			B_RECORDING					/* you're on the receiving end of recording; buffers are guaranteed to be late */
+				B_INCREASE_LATENCY,
+					// When late, increase the presentation time offset.
+				B_DROP_DATA,
+					// When late, try to catch up by dropping buffers.
+				B_RECORDING
+					// For nodes on the receiving end of recording.
+					// Buffers will always be late.
 			};
 
-
+			BMediaNode*			Acquire();
-		BMediaNode * Acquire();	/* return itself */
+			BMediaNode*			Release();
-		BMediaNode * Release();	/* release will decrement refcount, and delete if 0 */
 
 			const char*			Name() const;
 			media_node_id		ID() const;
@@ -148,154 +156,130 @@ public:
 			run_mode			RunMode() const;
 			BTimeSource*		TimeSource() const;
 
-	/* this port is what a media node listens to for commands */
+	// ID of the port used to listen to control messages.
 	virtual	port_id				ControlPort() const;
 
-virtual	BMediaAddOn* AddOn(
+	// Who instantiated this node or NULL for application internal class.
-				int32 * internal_id) const = 0;	/* Who instantiated you -- or NULL for app class */
+	virtual	BMediaAddOn*		AddOn(int32* internalID) const = 0;
 
-	/* These will be sent to anyone watching the MediaRoster. */
+	// Message constants which will be sent to anyone watching the
-	/* The message field "be:node_id" will contain the node ID. */
+	// MediaRoster. The message field "be:node_id" will contain the node ID.
 			enum node_error {
-			/* Note that these belong with the notifications in MediaDefs.h! */
+				// Note that these belong with the notifications in
-			/* They are here to provide compiler type checking in ReportError(). */
+				// MediaDefs.h! They are here to provide compiler type
+				// checking in ReportError().
 				B_NODE_FAILED_START					= 'TRI0',
-			B_NODE_FAILED_STOP,						// TRI1
+				B_NODE_FAILED_STOP					= 'TRI1',
-			B_NODE_FAILED_SEEK,						// TRI2
+				B_NODE_FAILED_SEEK					= 'TRI2',
-			B_NODE_FAILED_SET_RUN_MODE,				// TRI3
+				B_NODE_FAILED_SET_RUN_MODE			= 'TRI3',
-			B_NODE_FAILED_TIME_WARP,				// TRI4
+				B_NODE_FAILED_TIME_WARP				= 'TRI4',
-			B_NODE_FAILED_PREROLL,					// TRI5
+				B_NODE_FAILED_PREROLL				= 'TRI5',
-			B_NODE_FAILED_SET_TIME_SOURCE_FOR,		// TRI6
+				B_NODE_FAILED_SET_TIME_SOURCE_FOR	= 'TRI6',
-			/* display this node with a blinking exclamation mark or something */
+				B_NODE_IN_DISTRESS					= 'TRI7'
-			B_NODE_IN_DISTRESS						// TRI7
+				// What field 'TRIA' and up are used in MediaDefs.h
-			/* TRIA and up are used in MediaDefs.h */
 			};
 
 protected:
+	// Sends one of the above codes to anybody who's watching. You can
+	// provide an optional message with additional information.
+			status_t			ReportError(node_error what,
+									const BMessage* info = NULL);
 
-		/* Send one of the above codes to anybody who's watching. */
+	// When you've handled a stop request, call this function. If anyone is
-		status_t ReportError(
+	// listening for stop information from you, they will be notified.
-				node_error what,
+	// Especially important for offline capable Nodes.
-				const BMessage * info = NULL);	/* String "message" for instance */
+			status_t			NodeStopped(bigtime_t performanceTime);
+			void				TimerExpired(bigtime_t notifyPerformanceTime,
+									int32 cookie, status_t error = B_OK);
 
-		/* When you've handled a stop request, call this function. If anyone is */
+	// NOTE: Constructor initializes the reference count to 1.
-		/* listening for stop information from you, they will be notified. Especially */
+	explicit					BMediaNode(const char* name);
-		/* important for offline capable Nodes. */
-		status_t NodeStopped(
-				bigtime_t whenPerformance);	//	performance time
-		void TimerExpired(
-				bigtime_t notifyPoint,		//	performance time
-				int32 cookie,
-				status_t error = B_OK);
 
-explicit 	BMediaNode(		/* constructor sets refcount to 1 */
+				status_t		WaitForMessage(bigtime_t waitUntil,
-				const char * name);
+									uint32 flags = 0, void* _reserved_ = 0);
 
-		status_t WaitForMessage(
+	// These don't return errors; instead, they use the global error condition
-				bigtime_t waitUntil,
+	// reporter. A node is required to have a queue of at least one pending
-				uint32 flags = 0,
+	// command (plus TimeWarp) and is recommended to allow for at least one
-				void * _reserved_ = 0);
+	// pending command of each type. Allowing an arbitrary number of
-
+	// outstanding commands might be nice, but apps cannot depend on that
-		/* These don't return errors; instead, they use the global error condition reporter. */
+	// happening.
-		/* A node is required to have a queue of at least one pending command (plus TimeWarp) */
+	virtual	void				Start(bigtime_t atPerformanceTime);
-		/* and is recommended to allow for at least one pending command of each type. */
+	virtual	void				Stop(bigtime_t atPerformanceTime,
-		/* Allowing an arbitrary number of outstanding commands might be nice, but apps */
-		/* cannot depend on that happening. */
-virtual	void Start(
-				bigtime_t performance_time);
-virtual	void Stop(
-				bigtime_t performance_time,
 									bool immediate);
-virtual	void Seek(
+	virtual	void				Seek(bigtime_t toMediaTime,
-				bigtime_t media_time,
+									bigtime_t atPerformanceTime);
-				bigtime_t performance_time);
+	virtual	void				SetRunMode(run_mode mode);
-virtual	void SetRunMode(
+	virtual	void				TimeWarp(bigtime_t atRealTime,
-				run_mode mode);
+									bigtime_t toPerformanceTime);
-virtual	void TimeWarp(
-				bigtime_t at_real_time,
-				bigtime_t to_performance_time);
 	virtual	void				Preroll();
-virtual	void SetTimeSource(
+	virtual	void				SetTimeSource(BTimeSource* timeSource);
-				BTimeSource * time_source);
+
+public:
+	virtual	status_t			HandleMessage(int32 message, const void* data,
+									size_t size);
+
+	// Call this with messages you and your superclasses don't recognize.
+			void				HandleBadMessage(int32 code,
+									const void* buffer, size_t size);
+
+	// Called from derived system classes; you don't need to
+			void				AddNodeKind(uint64 kind);
+
+	// These just call the default global versions for now.
+			void*				operator new(size_t size);
+			void*				operator new(size_t size,
+									const std::nothrow_t&) throw();
+			void				operator delete(void* ptr);
+			void				operator delete(void* ptr,
+									const std::nothrow_t&) throw();
+
+protected:
+	// Hook method which is called when requests have completed, or failed.
+	virtual	status_t			RequestCompleted(
+									const media_request_info & info);
+
+	virtual	status_t			DeleteHook(BMediaNode* node);
+
+	virtual	void				NodeRegistered();
 
 public:
 
-virtual	status_t HandleMessage(
+	// Fill out your attributes in the provided array, returning however
-				int32 message,
+	// many you have.
-				const void * data,
+	virtual	status_t			GetNodeAttributes(
-				size_t size);
+									media_node_attribute* _attributes,
-		void HandleBadMessage(		/* call this with messages you and your superclasses don't recognize */
+									size_t inMaxCount);
-				int32 code,
-				const void * buffer,
-				size_t size);
 
-		/* Called from derived system classes; you don't need to */
+	virtual	status_t			AddTimer(bigtime_t atPerformanceTime,
-		void AddNodeKind(
+									int32 cookie);
-				uint64 kind);
-
-		//	These were not in 4.0.
-		//	We added them in 4.1 for future use. They just call
-		//	the default global versions for now.
-		void * operator new(
-				size_t size);
-		void * operator new(
-				size_t size,
-				const std::nothrow_t &) throw();
-		void operator delete(
-				void * ptr);
-#if !__MWERKS__
-		//	there's a bug in MWCC under R4.1 and earlier
-		void operator delete(
-				void * ptr, 
-				const std::nothrow_t &) throw();
-#endif
-
-protected:
-
-		/* Called when requests have completed, or failed. */
-virtual	status_t RequestCompleted(	/* reserved 0 */
-				const media_request_info & info);
 
 private:
 			friend class BTimeSource;
 			friend class BMediaRoster;
-	friend class BBufferProducer;	//	for getting _mNodeID
+			friend class BBufferProducer;
 			friend class BPrivate::media::TimeSourceObject;
 			friend class BPrivate::media::SystemTimeSourceObject;
 			friend class BPrivate::media::BMediaRosterEx;
 
-		// Deprecated in 4.1
+			// Deprecated in BeOS R4.1
 			int32				IncrementChangeTag();
 			int32				ChangeTag();
 			int32				MintChangeTag();
-		status_t ApplyChangeTag(
+			status_t			ApplyChangeTag(int32 previouslyReserved);
-				int32 previously_reserved);
-
-		/* Mmmh, stuffing! */
-protected:
-
-virtual		status_t DeleteHook(BMediaNode * node);		/* reserved 1 */
-
-virtual		void NodeRegistered();	/* reserved 2 */
-
-public:
-
-		/* fill out your attributes in the provided array, returning however many you have. */
-virtual		status_t GetNodeAttributes(	/* reserved 3 */
-					media_node_attribute * outAttributes,
-					size_t inMaxCount);
-
-virtual		status_t AddTimer(
-					bigtime_t at_performance_time,
-					int32 cookie);
 
 private:
-
+	// FBC padding and forbidden methods
-			status_t _Reserved_MediaNode_0(void *);		/* DeleteHook() */
+			status_t			_Reserved_MediaNode_0(void*);
-			status_t _Reserved_MediaNode_1(void *);		/* RequestCompletionHook() */
+				// RequestCompletionHook()
-			status_t _Reserved_MediaNode_2(void *);		/* NodeRegistered() */
+			status_t			_Reserved_MediaNode_1(void*);
-			status_t _Reserved_MediaNode_3(void *);		/* GetNodeAttributes() */
+				// DeleteHook()
-			status_t _Reserved_MediaNode_4(void *);		/* AddTimer() */
+			status_t			_Reserved_MediaNode_2(void*);
+				// NodeRegistered()
+			status_t			_Reserved_MediaNode_3(void*);
+				// GetNodeAttributes()
+			status_t			_Reserved_MediaNode_4(void*);
+				// AddTimer()
 	virtual	status_t			_Reserved_MediaNode_5(void*);
 	virtual	status_t			_Reserved_MediaNode_6(void*);
 	virtual	status_t			_Reserved_MediaNode_7(void*);
@@ -308,26 +292,26 @@ virtual		status_t _Reserved_MediaNode_13(void *);
 	virtual	status_t			_Reserved_MediaNode_14(void*);
 	virtual	status_t			_Reserved_MediaNode_15(void*);
 
-		BMediaNode();	/* private unimplemented */
+								BMediaNode();
-		BMediaNode(
+								BMediaNode(const BMediaNode& other);
-				const BMediaNode & clone);
+			BMediaNode&			operator=(const BMediaNode& other);
-		BMediaNode & operator=(
-				const BMediaNode & clone);
 
-		BMediaNode(		/* constructor sets refcount to 1 */
+private:
-				const char * name,
+								BMediaNode(const char* name,
-				media_node_id id,
+									media_node_id id, uint32 kinds);
-				uint32 kinds);
 
-		void _InitObject(const char *, media_node_id, uint64);
+			void				_InitObject(const char* name,
+									media_node_id id, uint64 kinds);
 
+private:
 			media_node_id		fNodeID;
 			BTimeSource*		fTimeSource;
 			int32				fRefCount;
 			char				fName[B_MEDIA_NAME_LENGTH];
 			run_mode			fRunMode;
-		int32 _mChangeCount;			//	deprecated
+
-		int32 _mChangeCountReserved;	//	deprecated
+			int32				_reserved[2];
+
 			uint64				fKinds;
 			media_node_id		fTimeSourceID;
 
@@ -337,24 +321,21 @@ virtual		status_t _Reserved_MediaNode_15(void *);
 			BControllable*		fControllableThis;
 			BTimeSource*		fTimeSourceThis;
 
-		bool _mReservedBool[4];
+			bool				_reservedBool[4];
 
 	mutable	port_id				fControlPort;
 
 			uint32				_reserved_media_node_[8];
 
-
-
 protected:
-
+	static	int32				NewChangeTag();
-static	int32 NewChangeTag();	//	for use by BBufferConsumer, mostly
+		// for use by BBufferConsumer, mostly
 
 private:
-		// dont' rename this one, it's static and needed for binary compatibility
+	// NOTE: Dont' rename this one, it's static and needed for binary
-static	int32 _m_changeTag;		//	not to be confused with _mChangeCount
+	// compatibility
+	static	int32 _m_changeTag;
+		// not to be confused with _mChangeCount
 };
 
-
+#endif // _MEDIA_NODE_H
-
-#endif /* _MEDIA_NODE_H */
-

src/kits/media/MediaNode.cpp

@@ -891,8 +891,6 @@ BMediaNode::_InitObject(const char *name, media_node_id id, uint64 kinds)
 		fName[B_MEDIA_NAME_LENGTH - 1] = 0;
 	}
 	fRunMode = B_INCREASE_LATENCY;
-	_mChangeCount = 0;			//	deprecated
-	_mChangeCountReserved = 0;	//	deprecated
 	fKinds = kinds;
 	fProducerThis = 0;
 	fConsumerThis = 0;