From 3644347545b0ff57d1a9f854cb81c8c5f6b77915 Mon Sep 17 00:00:00 2001
From: Klaus Schmidinger <vdr@tvdr.de>
Date: Thu, 15 Jun 2006 10:00:40 +0200
Subject: [PATCH] Added some comment to cDevice::GetDevice()

---
 HISTORY  |  2 ++
 device.c | 25 ++++++++++++++++---------
 device.h |  5 +++--
 3 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/HISTORY b/HISTORY
index 5b37632b..98b7d69e 100644
--- a/HISTORY
+++ b/HISTORY
@@ -4788,3 +4788,5 @@ Video Disk Recorder Revision History
 - Added "-fPIC" to the compiler options in Make.config.template when compiling
   plugins (thanks to Udo Richter). If you use your own Make.config file, you may
   want to add these lines there, too.
+- Added some comment to cDevice::GetDevice() to explain how the individual
+  conditions are put together to make a decision on which device to use.
diff --git a/device.c b/device.c
index 7d0fe12e..25c09f6a 100644
--- a/device.c
+++ b/device.c
@@ -4,7 +4,7 @@
  * See the main source file 'vdr.c' for copyright information and
  * how to reach the author.
  *
- * $Id: device.c 1.130 2006/05/27 11:14:42 kls Exp $
+ * $Id: device.c 1.131 2006/06/15 09:59:40 kls Exp $
  */
 
 #include "device.h"
@@ -281,19 +281,26 @@ cDevice *cDevice::GetDevice(int Index)
 cDevice *cDevice::GetDevice(const cChannel *Channel, int Priority, bool *NeedsDetachReceivers)
 {
   cDevice *d = NULL;
-  uint Impact = 0xFFFFFFFF;
+  uint Impact = 0xFFFFFFFF; // we're looking for a device with the least impact
   for (int i = 0; i < numDevices; i++) {
       bool ndr;
       if (device[i]->ProvidesChannel(Channel, Priority, &ndr)) { // this device is basicly able to do the job
+         // Put together an integer number that reflects the "impact" using
+         // this device would have on the overall system. Each condition is represented
+         // by one bit in the number (or several bits, if the condition is actually
+         // a numeric value). The sequence in which the conditions are listed corresponds
+         // to their individual severity, where the one listed first will make the most
+         // difference, because it results in the most significant bit of the result.
          uint imp = 0;
-         imp <<= 1; imp |= !device[i]->Receiving() || ndr;
-         imp <<= 1; imp |= device[i]->Receiving();
-         imp <<= 1; imp |= device[i] == ActualDevice();
-         imp <<= 1; imp |= device[i]->IsPrimaryDevice();
-         imp <<= 1; imp |= device[i]->HasDecoder();
-         imp <<= 8; imp |= min(max(device[i]->Priority() + MAXPRIORITY, 0), 0xFF);
-         imp <<= 8; imp |= min(max(device[i]->ProvidesCa(Channel), 0), 0xFF);
+         imp <<= 1; imp |= !device[i]->Receiving() || ndr;                         // use receiving devices if we don't need to detach existing receivers
+         imp <<= 1; imp |= device[i]->Receiving();                                 // avoid devices that are receiving
+         imp <<= 1; imp |= device[i] == ActualDevice();                            // avoid the actual device (in case of Transfer Mode)
+         imp <<= 1; imp |= device[i]->IsPrimaryDevice();                           // avoid the primary device
+         imp <<= 1; imp |= device[i]->HasDecoder();                                // avoid full featured cards
+         imp <<= 8; imp |= min(max(device[i]->Priority() + MAXPRIORITY, 0), 0xFF); // use the device with the lowest priority (+MAXPRIORITY to assure that values -99..99 can be used)
+         imp <<= 8; imp |= min(max(device[i]->ProvidesCa(Channel), 0), 0xFF);      // use the device that provides the lowest number of conditional access methods
          if (imp < Impact) {
+            // This device has less impact than any previous one, so we take it.
             Impact = imp;
             d = device[i];
             if (NeedsDetachReceivers)
diff --git a/device.h b/device.h
index ac721f59..dced092e 100644
--- a/device.h
+++ b/device.h
@@ -4,7 +4,7 @@
  * See the main source file 'vdr.c' for copyright information and
  * how to reach the author.
  *
- * $Id: device.h 1.78 2006/05/28 15:04:24 kls Exp $
+ * $Id: device.h 1.79 2006/06/15 09:32:48 kls Exp $
  */
 
 #ifndef __DEVICE_H
@@ -130,7 +130,8 @@ public:
          ///< \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.
+         ///< given Priority, with the least impact on active recordings and
+         ///< live viewing.
          ///< See ProvidesChannel() for more information on how
          ///< priorities are handled, and the meaning of NeedsDetachReceivers.
   static void Shutdown(void);