[reactos] 01/05: [NTOS:INBV] Add documentation to the progress-bar helpers. And fix a bug in them.
https://git.reactos.org/?p=reactos.git;a=commitdiff;h=e17f7d6994ea675cd52884...
commit e17f7d6994ea675cd5288458b456c05ddc386c4d Author: Hermès Bélusca-Maïto hermes.belusca-maito@reactos.org AuthorDate: Sun Feb 13 16:33:20 2022 +0100 Commit: Hermès Bélusca-Maïto hermes.belusca-maito@reactos.org CommitDate: Sun Feb 13 21:16:52 2022 +0100
[NTOS:INBV] Add documentation to the progress-bar helpers. And fix a bug in them.
In particular, the progress percentage specified to InbvUpdateProgressBar(), or the progress feedback made with InbvIndicateProgress() calls, is **relative** to the progress sub-range specified with a previous call to InbvSetProgressBarSubset() (by default, the range is 0...100%).
This functionality is used e.g. when the number of progress steps is unknown prior, for example when loading drivers: in this case progress is made within a given percentage range.
This bug has always been with us since 2010. --- ntoskrnl/inbv/inbv.c | 89 ++++++++++++++++++++++++++++++++-------- ntoskrnl/include/internal/inbv.h | 6 +-- 2 files changed, 73 insertions(+), 22 deletions(-)
diff --git a/ntoskrnl/inbv/inbv.c b/ntoskrnl/inbv/inbv.c index 049ff230555..4f6a8df1e0f 100644 --- a/ntoskrnl/inbv/inbv.c +++ b/ntoskrnl/inbv/inbv.c @@ -20,8 +20,6 @@
/* * ReactOS uses the same boot screen for all the products. - * Also it doesn't use a parallel system thread for the - * rotating "progress" bar. */
/* @@ -752,12 +750,23 @@ InbvSolidColorFill(IN ULONG Left, } }
+/** + * @brief + * Updates the progress bar percentage, relative to the current + * percentage sub-range previously set by InbvSetProgressBarSubset(). + * + * @param[in] Percentage + * The progress percentage, relative to the current sub-range. + * + * @return None. + **/ CODE_SEG("INIT") VOID NTAPI -InbvUpdateProgressBar(IN ULONG Progress) +InbvUpdateProgressBar( + _In_ ULONG Percentage) { - ULONG FillCount, BoundedProgress; + ULONG TotalProgress, FillCount;
/* Make sure the progress bar is enabled, that we own and are installed */ if (ShowProgressBar && @@ -765,8 +774,8 @@ InbvUpdateProgressBar(IN ULONG Progress) (InbvDisplayState == INBV_DISPLAY_STATE_OWNED)) { /* Compute fill count */ - BoundedProgress = (InbvProgressState.Floor / 100) + Progress; - FillCount = ProgressBarWidth * (InbvProgressState.Bias * BoundedProgress) / 1000000; + TotalProgress = InbvProgressState.Floor + (Percentage * InbvProgressState.Bias); + FillCount = ProgressBarWidth * TotalProgress / (100 * 100);
/* Acquire the lock */ InbvAcquireLock(); @@ -840,13 +849,29 @@ InbvScreenToBufferBlt(OUT PUCHAR Buffer, } }
+/** + * @brief + * Sets the screen coordinates of the loading progress bar and enable it. + * + * @param[in] Left + * @param[in] Top + * The left/top coordinates. + * + * (ReactOS-specific) + * @param[in] Width + * @param[in] Height + * The width/height of the progress bar. + * + * @return None. + **/ CODE_SEG("INIT") VOID NTAPI -InbvSetProgressBarCoordinates(IN ULONG Left, - IN ULONG Top, - IN ULONG Width, - IN ULONG Height) +InbvSetProgressBarCoordinates( + _In_ ULONG Left, + _In_ ULONG Top, + _In_ ULONG Width, + _In_ ULONG Height) { /* Update the coordinates */ ProgressBarLeft = Left; @@ -858,11 +883,28 @@ InbvSetProgressBarCoordinates(IN ULONG Left, ShowProgressBar = TRUE; }
+/** + * @brief + * Specifies a progress percentage sub-range. + * Further calls to InbvIndicateProgress() or InbvUpdateProgressBar() + * will update the progress percentage relative to this sub-range. + * In particular, the percentage provided to InbvUpdateProgressBar() + * is relative to this sub-range. + * + * @param[in] Floor + * The lower bound percentage of the sub-range (default: 0). + * + * @param[in] Ceiling + * The upper bound percentage of the sub-range (default: 100). + * + * @return None. + **/ CODE_SEG("INIT") VOID NTAPI -InbvSetProgressBarSubset(IN ULONG Floor, - IN ULONG Ceiling) +InbvSetProgressBarSubset( + _In_ ULONG Floor, + _In_ ULONG Ceiling) { /* Sanity checks */ ASSERT(Floor < Ceiling); @@ -871,9 +913,19 @@ InbvSetProgressBarSubset(IN ULONG Floor, /* Update the progress bar state */ InbvProgressState.Floor = Floor * 100; InbvProgressState.Ceiling = Ceiling * 100; - InbvProgressState.Bias = (Ceiling * 100) - Floor; + InbvProgressState.Bias = Ceiling - Floor; }
+/** + * @brief + * Gives some progress feedback, without specifying any explicit number + * of progress steps or percentage. + * The corresponding percentage is derived from the progress indicator's + * current count, capped to the number of expected calls to be made to + * this function (default: 25, see @b InbvProgressIndicator.Expected). + * + * @return None. + **/ CODE_SEG("INIT") VOID NTAPI @@ -884,13 +936,14 @@ InbvIndicateProgress(VOID) /* Increase progress */ InbvProgressIndicator.Count++;
- /* Compute new percentage */ - Percentage = min(100 * InbvProgressIndicator.Count / - InbvProgressIndicator.Expected, - 99); + /* Compute the new percentage - Don't go over 100% */ + Percentage = 100 * InbvProgressIndicator.Count / + InbvProgressIndicator.Expected; + Percentage = min(Percentage, 99); + if (Percentage != InbvProgressIndicator.Percentage) { - /* Percentage has moved, update the progress bar */ + /* Percentage has changed, update the progress bar */ InbvProgressIndicator.Percentage = Percentage; InbvUpdateProgressBar(Percentage); } diff --git a/ntoskrnl/include/internal/inbv.h b/ntoskrnl/include/internal/inbv.h index 3dbc8d9896d..0fb7042c71c 100644 --- a/ntoskrnl/include/internal/inbv.h +++ b/ntoskrnl/include/internal/inbv.h @@ -36,9 +36,7 @@ InbvBitBlt( CODE_SEG("INIT") VOID NTAPI -InbvIndicateProgress( - VOID -); +InbvIndicateProgress(VOID);
CODE_SEG("INIT") VOID @@ -52,7 +50,7 @@ CODE_SEG("INIT") VOID NTAPI InbvUpdateProgressBar( - IN ULONG Progress + _In_ ULONG Percentage );
//
-
Hermès Bélusca-Maïto