diff options
Diffstat (limited to 'device.h')
| -rw-r--r-- | device.h | 366 |
1 files changed, 191 insertions, 175 deletions
@@ -4,7 +4,7 @@ * See the main source file 'vdr.c' for copyright information and * how to reach the author. * - * $Id: device.h 1.27 2002/11/03 11:16:11 kls Exp $ + * $Id: device.h 1.28 2002/12/15 14:40:11 kls Exp $ */ #ifndef __DEVICE_H @@ -50,6 +50,8 @@ class cPlayer; class cReceiver; class cSpuDecoder; +/// The cDevice class is the base from which actual devices can be derived. + class cDevice : public cThread { private: static int numDevices; @@ -58,32 +60,35 @@ private: static cDevice *primaryDevice; public: static int NumDevices(void) { return numDevices; } - // Returns the total number of devices. + ///< Returns the total number of devices. static void SetUseDevice(int n); - // Sets the 'useDevice' flag of the given device. - // If this function is not called before initializing, all devices - // will be used. + ///< Sets the 'useDevice' flag of the given device. + ///< If this function is not called before initializing, all devices + ///< will be used. static bool UseDevice(int n) { return useDevice == 0 || (useDevice & (1 << n)) != 0; } - // Tells whether the device with the given card index shall be used in - // this instance of VDR. + ///< Tells whether the device with the given card index shall be used in + ///< this instance of VDR. static bool SetPrimaryDevice(int n); - // Sets the primary device to 'n' (which must be in the range - // 1...numDevices) and returns true if this was possible. + ///< Sets the primary device to 'n'. + ///< \param n must be in the range 1...numDevices. + ///< \return true if this was possible. static cDevice *PrimaryDevice(void) { return primaryDevice; } - // Returns the primary device. + ///< Returns the primary device. static cDevice *GetDevice(int Index); - // Returns the device with the Index (if Index is in the range - // 0..numDevices-1, NULL otherwise). + ///< Gets the device with the given Index. + ///< \param Index must be in the range 0..numDevices-1. + ///< \return A pointer to the device, or NULL if the Index was invalid. static cDevice *GetDevice(const cChannel *Channel, int Priority = -1, bool *NeedsDetachReceivers = NULL); - // Returns a device that is able to receive the given Channel at the - // given Priority (see ProvidesChannel() for more information on how - // priorities are handled, and the meaning of NeedsDetachReceivers). + ///< Returns a device that is able to receive the given Channel at the + ///< given Priority. + ///< See ProvidesChannel() for more information on how + ///< priorities are handled, and the meaning of NeedsDetachReceivers. static void SetCaCaps(int Index = -1); - // Sets the CaCaps of the given device according to the Setup data. - // By default the CaCaps of all devices are set. + ///< Sets the CaCaps of the given device according to the Setup data. + ///< By default the CaCaps of all devices are set. static void Shutdown(void); - // Closes down all devices. - // Must be called at the end of the program. + ///< Closes down all devices. + ///< Must be called at the end of the program. private: static int nextCardIndex; int cardIndex; @@ -92,49 +97,50 @@ protected: cDevice(void); virtual ~cDevice(); static int NextCardIndex(int n = 0); - // Each device in a given machine must have a unique card index, which - // will be used to identify the device for assigning Ca parameters and - // deciding whether to actually use that device in this particular - // instance of VDR. Every time a new cDevice is created, it will be - // given the current nextCardIndex, and then nextCardIndex will be - // automatically incremented by 1. A derived class can determine whether - // a given device shall be used by checking UseDevice(NextCardIndex()). - // If a device is skipped, or if there are possible device indexes left - // after a derived class has set up all its devices, NextCardIndex(n) - // must be called, where n is the number of card indexes to skip. + ///< Calculates the next card index. + ///< Each device in a given machine must have a unique card index, which + ///< will be used to identify the device for assigning Ca parameters and + ///< deciding whether to actually use that device in this particular + ///< instance of VDR. Every time a new cDevice is created, it will be + ///< given the current nextCardIndex, and then nextCardIndex will be + ///< automatically incremented by 1. A derived class can determine whether + ///< a given device shall be used by checking UseDevice(NextCardIndex()). + ///< If a device is skipped, or if there are possible device indexes left + ///< after a derived class has set up all its devices, NextCardIndex(n) + ///< must be called, where n is the number of card indexes to skip. virtual void MakePrimaryDevice(bool On); - // Informs a device that it will be the primary device. If there is - // anything the device needs to set up when it becomes the primary - // device (On = true) or to shut down when it no longer is the primary - // device (On = false), it should do so in this function. + ///< Informs a device that it will be the primary device. If there is + ///< anything the device needs to set up when it becomes the primary + ///< device (On = true) or to shut down when it no longer is the primary + ///< device (On = false), it should do so in this function. public: bool IsPrimaryDevice(void) const { return this == primaryDevice; } int CardIndex(void) const { return cardIndex; } - // Returns the card index of this device (0 ... MAXDEVICES - 1). + ///< Returns the card index of this device (0 ... MAXDEVICES - 1). int DeviceNumber(void) const; - // Returns number of this device (0 ... MAXDEVICES - 1). + ///< Returns the number of this device (0 ... MAXDEVICES - 1). int ProvidesCa(int Ca) const; - // Checks whether this device provides the given value in its - // caCaps. Returns 0 if the value is not provided, 1 if only this - // value is provided, and > 1 if this and other values are provided. - // If the given value is equal to the number of this device, - // 1 is returned. If it is 0 (FTA), 1 plus the number of other values - // in caCaps is returned. + ///< Checks whether this device provides the given value in its + ///< caCaps. Returns 0 if the value is not provided, 1 if only this + ///< value is provided, and > 1 if this and other values are provided. + ///< If the given value is equal to the number of this device, + ///< 1 is returned. If it is 0 (FTA), 1 plus the number of other values + ///< in caCaps is returned. virtual bool HasDecoder(void) const; - // Tells whether this device has an MPEG decoder. + ///< Tells whether this device has an MPEG decoder. // OSD facilities public: virtual cOsdBase *NewOsd(int x, int y); - // Creates a new cOsdBase object that can be used by the cOsd class - // to display information on the screen, with the upper left corner - // of the OSD at the given coordinates. If a derived cDevice doesn't - // implement this function, NULL will be returned by default (which - // means the device has no OSD capabilities). + ///< Creates a new cOsdBase object that can be used by the cOsd class + ///< to display information on the screen, with the upper left corner + ///< of the OSD at the given coordinates. If a derived cDevice doesn't + ///< implement this function, NULL will be returned by default (which + ///< means the device has no OSD capabilities). virtual cSpuDecoder *GetSpuDecoder(void); - // Returns a pointer to the device's SPU decoder (or NULL, if this - // device doesn't have an SPU decoder). + ///< Returns a pointer to the device's SPU decoder (or NULL, if this + ///< device doesn't have an SPU decoder). // Channel facilities @@ -142,38 +148,38 @@ protected: static int currentChannel; public: virtual bool ProvidesSource(int Source) const; - // Returns true if this device can provide the given source. + ///< Returns true if this device can provide the given source. virtual bool ProvidesChannel(const cChannel *Channel, int Priority = -1, bool *NeedsDetachReceivers = NULL) const; - // Returns true if this device can provide the given channel. - // In case the device has cReceivers attached to it or it is the primary - // device, Priority is used to decide whether the caller's request can - // be honored. - // The special Priority value -1 will tell the caller whether this device - // is principally able to provide the given Channel, regardless of any - // attached cReceivers. - // If NeedsDetachReceivers is given, the resulting value in it will tell the - // caller whether or not it will have to detach any currently attached - // receivers from this device before calling SwitchChannel. Note - // that the return value in NeedsDetachReceivers is only meaningful if the - // function itself actually returns true. - // The default implementation always returns false, so a derived cDevice - // class that can provide channels must implement this function. + ///< Returns true if this device can provide the given channel. + ///< In case the device has cReceivers attached to it or it is the primary + ///< device, Priority is used to decide whether the caller's request can + ///< be honored. + ///< The special Priority value -1 will tell the caller whether this device + ///< is principally able to provide the given Channel, regardless of any + ///< attached cReceivers. + ///< If NeedsDetachReceivers is given, the resulting value in it will tell the + ///< caller whether or not it will have to detach any currently attached + ///< receivers from this device before calling SwitchChannel. Note + ///< that the return value in NeedsDetachReceivers is only meaningful if the + ///< function itself actually returns true. + ///< The default implementation always returns false, so a derived cDevice + ///< class that can provide channels must implement this function. bool SwitchChannel(const cChannel *Channel, bool LiveView); - // Switches the device to the given Channel, initiating transfer mode - // if necessary. + ///< Switches the device to the given Channel, initiating transfer mode + ///< if necessary. static bool SwitchChannel(int Direction); - // Switches the primary device to the next available channel in the given - // Direction (only the sign of Direction is evaluated, positive values - // switch to higher channel numbers). + ///< Switches the primary device to the next available channel in the given + ///< Direction (only the sign of Direction is evaluated, positive values + ///< switch to higher channel numbers). private: eSetChannelResult SetChannel(const cChannel *Channel, bool LiveView); - // Sets the device to the given channel (general setup). + ///< Sets the device to the given channel (general setup). protected: virtual bool SetChannelDevice(const cChannel *Channel, bool LiveView); - // Sets the device to the given channel (actual physical setup). + ///< Sets the device to the given channel (actual physical setup). public: static int CurrentChannel(void) { return primaryDevice ? currentChannel : 0; } - // Returns the number of the current channel on the primary device. + ///< Returns the number of the current channel on the primary device. // PID handle facilities @@ -191,33 +197,43 @@ protected: }; cPidHandle pidHandles[MAXPIDHANDLES]; bool HasPid(int Pid) const; - // Returns true if this device is currently receiving the given PID. + ///< Returns true if this device is currently receiving the given PID. bool AddPid(int Pid, ePidType PidType = ptOther); - // Adds a PID to the set of PIDs this device shall receive. + ///< Adds a PID to the set of PIDs this device shall receive. void DelPid(int Pid); - // Deletes a PID from the set of PIDs this device shall receive. + ///< Deletes a PID from the set of PIDs this device shall receive. virtual bool SetPid(cPidHandle *Handle, int Type, bool On); - // Does the actual PID setting on this device. - // On indicates whether the PID shall be added or deleted. - // Handle->handle can be used by the device to store information it - // needs to receive this PID (for instance a file handle). - // Handle->used indicated how many receivers are using this PID. - // Type indicates some special types of PIDs, which the device may - // need to set in a specific way. + ///< Does the actual PID setting on this device. + ///< On indicates whether the PID shall be added or deleted. + ///< Handle->handle can be used by the device to store information it + ///< needs to receive this PID (for instance a file handle). + ///< Handle->used indicated how many receivers are using this PID. + ///< Type indicates some special types of PIDs, which the device may + ///< need to set in a specific way. // Image Grab facilities public: virtual bool GrabImage(const char *FileName, bool Jpeg = true, int Quality = -1, int SizeX = -1, int SizeY = -1); - // Grabs the currently visible screen image into the given file, with the - // given parameters. + ///< Capture a single frame as an image. + ///< Grabs the currently visible screen image into the given file, with the + ///< given parameters. + ///< \param FileName The name of the file to write. Should include the proper extension. + ///< \param Jpeg If true will write a JPEG file. Otherwise a PNM file will be written. + ///< \param Quality The compression factor for JPEG. 1 will create a very blocky + ///< and small image, 70..80 will yield reasonable quality images while keeping the + ///< image file size around 50 KB for a full frame. The default will create a big + ///< but very high quality image. + ///< \param SizeX The number of horizontal pixels in the frame (default is the current screen width). + ///< \param SizeY The number of vertical pixels in the frame (default is the current screen height). + ///< \return True if all went well. */ // Video format facilities public: virtual void SetVideoFormat(bool VideoFormat16_9); - // Sets the output video format to either 16:9 or 4:3 (only useful - // if this device has an MPEG decoder). + ///< Sets the output video format to either 16:9 or 4:3 (only useful + ///< if this device has an MPEG decoder). // Audio facilities @@ -226,51 +242,51 @@ private: int volume; protected: virtual void SetVolumeDevice(int Volume); - // Sets the audio volume on this device (Volume = 0...255). + ///< Sets the audio volume on this device (Volume = 0...255). virtual int NumAudioTracksDevice(void) const; - // Returns the number of audio tracks that are currently available on this - // device. The default return value is 0, meaning that this device - // doesn't have multiple audio track capabilities. The return value may - // change with every call and need not necessarily be the number of list - // entries returned by GetAudioTracksDevice(). This function is mainly called to - // decide whether there should be an "Audio" button in a menu. + ///< Returns the number of audio tracks that are currently available on this + ///< device. The default return value is 0, meaning that this device + ///< doesn't have multiple audio track capabilities. The return value may + ///< change with every call and need not necessarily be the number of list + ///< entries returned by GetAudioTracksDevice(). This function is mainly called to + ///< decide whether there should be an "Audio" button in a menu. virtual const char **GetAudioTracksDevice(int *CurrentTrack = NULL) const; - // Returns a list of currently available audio tracks. The last entry in the - // list must be NULL. The number of entries does not necessarily have to be - // the same as returned by a previous call to NumAudioTracksDevice(). - // If CurrentTrack is given, it will be set to the index of the current track - // in the returned list. Note that the list must not be changed after it has - // been returned by a call to GetAudioTracksDevice()! The only time the list may - // change is *inside* the GetAudioTracksDevice() function. - // By default the return value is NULL and CurrentTrack, if given, will not - // have any meaning. + ///< Returns a list of currently available audio tracks. The last entry in the + ///< list must be NULL. The number of entries does not necessarily have to be + ///< the same as returned by a previous call to NumAudioTracksDevice(). + ///< If CurrentTrack is given, it will be set to the index of the current track + ///< in the returned list. Note that the list must not be changed after it has + ///< been returned by a call to GetAudioTracksDevice()! The only time the list may + ///< change is *inside* the GetAudioTracksDevice() function. + ///< By default the return value is NULL and CurrentTrack, if given, will not + ///< have any meaning. virtual void SetAudioTrackDevice(int Index); - // Sets the current audio track to the given value, which should be within the - // range of the list returned by a previous call to GetAudioTracksDevice() - // (otherwise nothing will happen). + ///< Sets the current audio track to the given value, which should be within the + ///< range of the list returned by a previous call to GetAudioTracksDevice() + ///< (otherwise nothing will happen). public: bool IsMute(void) const { return mute; } bool ToggleMute(void); - // Turns the volume off or on and returns the new mute state. + ///< Turns the volume off or on and returns the new mute state. void SetVolume(int Volume, bool Absolute = false); - // Sets the volume to the given value, either absolutely or relative to - // the current volume. + ///< Sets the volume to the given value, either absolutely or relative to + ///< the current volume. static int CurrentVolume(void) { return primaryDevice ? primaryDevice->volume : 0; }//XXX??? int NumAudioTracks(void) const; - // Returns the number of audio tracks that are currently available on this - // device or a player attached to it. + ///< Returns the number of audio tracks that are currently available on this + ///< device or a player attached to it. const char **GetAudioTracks(int *CurrentTrack = NULL) const; - // Returns a list of currently available audio tracks. The last entry in the - // list is NULL. The number of entries does not necessarily have to be - // the same as returned by a previous call to NumAudioTracks(). - // If CurrentTrack is given, it will be set to the index of the current track - // in the returned list. - // By default the return value is NULL and CurrentTrack, if given, will not - // have any meaning. + ///< Returns a list of currently available audio tracks. The last entry in the + ///< list is NULL. The number of entries does not necessarily have to be + ///< the same as returned by a previous call to NumAudioTracks(). + ///< If CurrentTrack is given, it will be set to the index of the current track + ///< in the returned list. + ///< By default the return value is NULL and CurrentTrack, if given, will not + ///< have any meaning. void SetAudioTrack(int Index); - // Sets the current audio track to the given value, which should be within the - // range of the list returned by a previous call to GetAudioTracks() (otherwise - // nothing will happen). + ///< Sets the current audio track to the given value, which should be within the + ///< range of the list returned by a previous call to GetAudioTracks() (otherwise + ///< nothing will happen). // Player facilities @@ -279,54 +295,54 @@ private: bool playerDetached; protected: virtual bool CanReplay(void) const; - // Returns true if this device can currently start a replay session. + ///< Returns true if this device can currently start a replay session. virtual bool SetPlayMode(ePlayMode PlayMode); - // Sets the device into the given play mode. - // Returns true if the operation was successful. + ///< Sets the device into the given play mode. + ///< \return true if the operation was successful. public: virtual void TrickSpeed(int Speed); - // Sets the device into a mode where replay is done slower. - // Every single frame shall then be displayed the given number of - // times. + ///< Sets the device into a mode where replay is done slower. + ///< Every single frame shall then be displayed the given number of + ///< times. virtual void Clear(void); - // Clears all video and audio data from the device. - // A derived class must call the base class function to make sure - // all registered cAudio objects are notified. + ///< Clears all video and audio data from the device. + ///< A derived class must call the base class function to make sure + ///< all registered cAudio objects are notified. virtual void Play(void); - // Sets the device into play mode (after a previous trick - // mode). + ///< Sets the device into play mode (after a previous trick + ///< mode). virtual void Freeze(void); - // Puts the device into "freeze frame" mode. + ///< Puts the device into "freeze frame" mode. virtual void Mute(void); - // Turns off audio while replaying. - // A derived class must call the base class function to make sure - // all registered cAudio objects are notified. + ///< Turns off audio while replaying. + ///< A derived class must call the base class function to make sure + ///< all registered cAudio objects are notified. virtual void StillPicture(const uchar *Data, int Length); - // Displays the given I-frame as a still picture. + ///< Displays the given I-frame as a still picture. virtual bool Poll(cPoller &Poller, int TimeoutMs = 0); - // Returns true if the device itself or any of the file handles in - // Poller is ready for further action. - // If TimeoutMs is not zero, the device will wait up to the given number - // of milleseconds before returning in case there is no immediate - // need for data. + ///< Returns true if the device itself or any of the file handles in + ///< Poller is ready for further action. + ///< If TimeoutMs is not zero, the device will wait up to the given number + ///< of milleseconds before returning in case there is no immediate + ///< need for data. virtual int PlayVideo(const uchar *Data, int Length); - // Actually plays the given data block as video. The data must be - // part of a PES (Packetized Elementary Stream) which can contain - // one video and one audio strem. + ///< Actually plays the given data block as video. The data must be + ///< part of a PES (Packetized Elementary Stream) which can contain + ///< one video and one audio strem. virtual void PlayAudio(const uchar *Data, int Length); - // Plays additional audio streams, like Dolby Digital. - // A derived class must call the base class function to make sure data - // is distributed to all registered cAudio objects. + ///< Plays additional audio streams, like Dolby Digital. + ///< A derived class must call the base class function to make sure data + ///< is distributed to all registered cAudio objects. bool Replaying(void) const; - // Returns true if we are currently replaying. + ///< Returns true if we are currently replaying. void StopReplay(void); - // Stops the current replay session (if any). + ///< Stops the current replay session (if any). bool AttachPlayer(cPlayer *Player); - // Attaches the given player to this device. + ///< Attaches the given player to this device. void Detach(cPlayer *Player); - // Detaches the given player from this device. + ///< Detaches the given player from this device. bool PlayerDetached(void); - // Returns true if a player has been detached and resets the 'playerDetached' flag. + ///< Returns true if a player has been detached and resets the 'playerDetached' flag. // Receiver facilities @@ -335,39 +351,39 @@ private: int CanShift(int Ca, int Priority, int UsedCards = 0) const; protected: int Priority(void) const; - // Returns the priority of the current receiving session (0..MAXPRIORITY), - // or -1 if no receiver is currently active. The primary device will - // always return at least Setup.PrimaryLimit-1. + ///< Returns the priority of the current receiving session (0..MAXPRIORITY), + ///< or -1 if no receiver is currently active. The primary device will + ///< always return at least Setup.PrimaryLimit-1. virtual bool OpenDvr(void); - // Opens the DVR of this device and prepares it to deliver a Transport - // Stream for use in a cReceiver. + ///< Opens the DVR of this device and prepares it to deliver a Transport + ///< Stream for use in a cReceiver. virtual void CloseDvr(void); - // Shuts down the DVR. + ///< Shuts down the DVR. virtual bool GetTSPacket(uchar *&Data); - // Gets exactly one TS packet from the DVR of this device and returns - // a pointer to it in Data. Only the first 188 bytes (TS_SIZE) Data - // points to are valid and may be accessed. If there is currently no - // new data available, Data will be set to NULL. The function returns - // false in case of a non recoverable error, otherwise it returns true, - // even if Data is NULL. + ///< Gets exactly one TS packet from the DVR of this device and returns + ///< a pointer to it in Data. Only the first 188 bytes (TS_SIZE) Data + ///< points to are valid and may be accessed. If there is currently no + ///< new data available, Data will be set to NULL. The function returns + ///< false in case of a non recoverable error, otherwise it returns true, + ///< even if Data is NULL. public: int Ca(void) const; - // Returns the ca of the current receiving session(s). + ///< Returns the ca of the current receiving session(s). bool Receiving(bool CheckAny = false) const; - // Returns true if we are currently receiving. + ///< Returns true if we are currently receiving. bool AttachReceiver(cReceiver *Receiver); - // Attaches the given receiver to this device. + ///< Attaches the given receiver to this device. void Detach(cReceiver *Receiver); - // Detaches the given receiver from this device. + ///< Detaches the given receiver from this device. }; -// Derived cDevice classes that can receive channels will have to provide -// Transport Stream (TS) packets one at a time. cTSBuffer implements a -// simple buffer that allows the device to read a larger amount of data -// from the driver with each call to Read(), thus avoiding the overhead -// of getting each TS packet separately from the driver. It also makes -// sure the returned data points to a TS packet and automatically -// re-synchronizes after broken packet. +/// Derived cDevice classes that can receive channels will have to provide +/// Transport Stream (TS) packets one at a time. cTSBuffer implements a +/// simple buffer that allows the device to read a larger amount of data +/// from the driver with each call to Read(), thus avoiding the overhead +/// of getting each TS packet separately from the driver. It also makes +/// sure the returned data points to a TS packet and automatically +/// re-synchronizes after broken packet. class cTSBuffer { private: |