@@ -1,20 +1,193 @@
|
||||
/**
|
||||
* @file InactivityTracker.h
|
||||
* @brief Inactivity tracking system for monitoring user interaction timeouts
|
||||
* @details This header defines the InactivityTracker class which monitors user
|
||||
* activity and triggers timeout callbacks when the system remains inactive
|
||||
* for a specified duration. It provides essential functionality for power
|
||||
* management, screen savers, and automatic system state transitions.
|
||||
* @author System Control Team
|
||||
* @date 2025-06-20
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include <cstdint>
|
||||
#include <functional>
|
||||
|
||||
/**
|
||||
* @class InactivityTracker
|
||||
* @brief Activity monitoring class for detecting user inactivity periods
|
||||
* @details This class provides a robust mechanism for tracking user activity and
|
||||
* triggering automatic actions when the system remains inactive for a
|
||||
* configured timeout period. It is commonly used for implementing power
|
||||
* saving features, automatic screen savers, session timeouts, and other
|
||||
* time-based system behaviors.
|
||||
*
|
||||
* The InactivityTracker operates by:
|
||||
* - Continuously tracking elapsed time since the last user activity
|
||||
* - Comparing elapsed time against a configurable timeout threshold
|
||||
* - Executing a callback function when the timeout is reached
|
||||
* - Providing methods to reset the timer when activity is detected
|
||||
* - Supporting enable/disable functionality for dynamic control
|
||||
*
|
||||
* Key features include:
|
||||
* - Configurable timeout duration in milliseconds
|
||||
* - Custom callback function execution on timeout
|
||||
* - Activity reset capability for responsive user interaction
|
||||
* - Enable/disable control for conditional monitoring
|
||||
* - High-resolution timing support using 64-bit millisecond precision
|
||||
*
|
||||
* Common use cases:
|
||||
* - Screen saver activation after idle periods
|
||||
* - Automatic screen dimming or shutdown
|
||||
* - Session timeout management
|
||||
* - Power management and battery conservation
|
||||
* - User interface state transitions
|
||||
* - Security lockout after inactivity
|
||||
*
|
||||
* The class is designed to be lightweight and efficient, suitable for
|
||||
* real-time applications where precise timing and minimal overhead are important.
|
||||
*
|
||||
* @note This class requires regular update calls to function properly.
|
||||
* @note The timeout callback is executed once per timeout period and will
|
||||
* not repeat until the tracker is reset and times out again.
|
||||
*
|
||||
* @see Widget for integration with UI components
|
||||
* @see Menu for menu timeout implementations
|
||||
*/
|
||||
class InactivityTracker
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* @brief Constructs an InactivityTracker with specified timeout and callback
|
||||
* @param timeoutMs Timeout duration in milliseconds before triggering callback
|
||||
* @param onTimeout Callback function to execute when timeout is reached
|
||||
*
|
||||
* @pre timeoutMs must be greater than 0 for meaningful timeout behavior
|
||||
* @pre onTimeout must be a valid callable function object
|
||||
* @post InactivityTracker is initialized, enabled, and ready for activity monitoring
|
||||
*
|
||||
* @details The constructor initializes the inactivity tracker with the specified
|
||||
* timeout duration and callback function. The tracker starts in an enabled
|
||||
* state with zero elapsed time, ready to begin monitoring user activity.
|
||||
*
|
||||
* The timeout callback function can perform any necessary actions when inactivity
|
||||
* is detected, such as:
|
||||
* - Activating screen savers or power saving modes
|
||||
* - Transitioning to different application states
|
||||
* - Logging inactivity events
|
||||
* - Triggering security lockouts
|
||||
* - Initiating automatic save operations
|
||||
*
|
||||
* @note The tracker begins monitoring immediately upon construction.
|
||||
* @note The callback function should be lightweight to avoid blocking
|
||||
* the main application thread during timeout processing.
|
||||
*
|
||||
* Example usage:
|
||||
* @code
|
||||
* auto tracker = InactivityTracker(30000, []() {
|
||||
* // Activate screen saver after 30 seconds of inactivity
|
||||
* activateScreenSaver();
|
||||
* });
|
||||
* @endcode
|
||||
*/
|
||||
InactivityTracker(uint64_t timeoutMs, std::function<void()> onTimeout);
|
||||
|
||||
/**
|
||||
* @brief Updates the inactivity timer and checks for timeout conditions
|
||||
* @param dt Delta time in milliseconds since the last update call
|
||||
*
|
||||
* @details This method must be called regularly (typically every frame) to
|
||||
* maintain accurate timing and timeout detection. It increments the
|
||||
* elapsed time counter and triggers the timeout callback when the
|
||||
* configured timeout duration is reached.
|
||||
*
|
||||
* The update process:
|
||||
* - Adds the delta time to the elapsed time counter (if enabled)
|
||||
* - Compares elapsed time against the configured timeout threshold
|
||||
* - Executes the timeout callback if the threshold is exceeded
|
||||
* - Continues monitoring until reset or disabled
|
||||
*
|
||||
* @note This method should be called consistently from the main application
|
||||
* loop to ensure accurate timing behavior.
|
||||
* @note The timeout callback is executed only once per timeout period.
|
||||
* @note If the tracker is disabled, elapsed time is not updated.
|
||||
*
|
||||
* @see reset() to restart the inactivity timer
|
||||
* @see setEnabled() to control monitoring state
|
||||
*/
|
||||
void update(uint64_t dt);
|
||||
|
||||
/**
|
||||
* @brief Resets the inactivity timer to indicate recent user activity
|
||||
*
|
||||
* @details This method should be called whenever user activity is detected
|
||||
* to restart the inactivity timeout period. It resets the elapsed
|
||||
* time counter to zero, effectively extending the timeout deadline
|
||||
* and preventing timeout callback execution until the full timeout
|
||||
* duration elapses again without further resets.
|
||||
*
|
||||
* Common scenarios for calling reset():
|
||||
* - Button presses or key events
|
||||
* - Mouse movement or touch input
|
||||
* - Menu navigation or selection actions
|
||||
* - Any user interface interaction
|
||||
* - System activity that should extend the timeout
|
||||
*
|
||||
* @post Elapsed time is reset to zero, restarting the timeout period
|
||||
*
|
||||
* @note This method can be called at any time, even when the tracker
|
||||
* is disabled, to prepare for future monitoring.
|
||||
* @note Frequent reset calls from active user interaction will prevent
|
||||
* timeout callback execution, which is the intended behavior.
|
||||
*
|
||||
* Example usage:
|
||||
* @code
|
||||
* void onButtonPress() {
|
||||
* tracker.reset(); // User activity detected, restart timeout
|
||||
* // Handle button press...
|
||||
* }
|
||||
* @endcode
|
||||
*/
|
||||
void reset();
|
||||
|
||||
/**
|
||||
* @brief Enables or disables inactivity monitoring
|
||||
* @param enabled True to enable monitoring, false to disable
|
||||
*
|
||||
* @details This method controls whether the inactivity tracker actively
|
||||
* monitors for timeouts. When disabled, the elapsed time counter
|
||||
* is not updated during update() calls, effectively pausing the
|
||||
* timeout detection without losing the current elapsed time state.
|
||||
*
|
||||
* Use cases for disabling:
|
||||
* - Temporary suspension during system operations
|
||||
* - Context-sensitive monitoring (disable in certain application states)
|
||||
* - Power management control (disable during low-power modes)
|
||||
* - User preference settings (allow users to disable timeouts)
|
||||
* - Development and debugging (disable for testing)
|
||||
*
|
||||
* When re-enabled, monitoring resumes from the current elapsed time state,
|
||||
* allowing for seamless pause/resume functionality.
|
||||
*
|
||||
* @post Monitoring state is updated according to the enabled parameter
|
||||
*
|
||||
* @note Disabling the tracker does not reset the elapsed time counter.
|
||||
* @note The timeout callback will not be executed while disabled, even
|
||||
* if the timeout threshold would otherwise be exceeded.
|
||||
* @note Enabling/disabling can be done at any time during operation.
|
||||
*
|
||||
* Example usage:
|
||||
* @code
|
||||
* tracker.setEnabled(false); // Pause monitoring during critical operation
|
||||
* performCriticalOperation();
|
||||
* tracker.setEnabled(true); // Resume monitoring after completion
|
||||
* @endcode
|
||||
*/
|
||||
void setEnabled(bool enabled);
|
||||
|
||||
private:
|
||||
uint64_t m_timeoutMs;
|
||||
uint64_t m_elapsedTime;
|
||||
bool m_enabled;
|
||||
std::function<void()> m_onTimeout;
|
||||
};
|
||||
uint64_t m_timeoutMs; ///< Timeout duration in milliseconds before callback execution
|
||||
uint64_t m_elapsedTime; ///< Current elapsed time since last reset in milliseconds
|
||||
bool m_enabled; ///< Flag indicating whether monitoring is currently active
|
||||
std::function<void()> m_onTimeout; ///< Callback function executed when timeout threshold is reached
|
||||
};
|
||||
@@ -51,9 +51,58 @@ class Widget
|
||||
*/
|
||||
virtual ~Widget() = default;
|
||||
|
||||
/**
|
||||
* @brief Called when the widget becomes active or enters the foreground
|
||||
* @details This method is invoked when the widget transitions from inactive
|
||||
* to active state, such as when it becomes the current screen or
|
||||
* gains focus. Derived classes can override this method to perform
|
||||
* initialization tasks, reset state, or prepare for user interaction.
|
||||
*
|
||||
* @note The base implementation is empty, allowing derived classes to override
|
||||
* only if entry behavior is needed.
|
||||
* @note This method is typically called by the UI management system during
|
||||
* screen transitions or focus changes.
|
||||
*/
|
||||
virtual void enter();
|
||||
|
||||
/**
|
||||
* @brief Called when the widget is temporarily paused or loses focus
|
||||
* @details This method is invoked when the widget needs to suspend its
|
||||
* operations temporarily, such as when another widget takes focus
|
||||
* or the system enters a paused state. Derived classes can override
|
||||
* this method to pause animations, save state, or reduce resource usage.
|
||||
*
|
||||
* @note The base implementation is empty, allowing derived classes to override
|
||||
* only if pause behavior is needed.
|
||||
* @note The widget should be prepared to resume from this state when resume() is called.
|
||||
*/
|
||||
virtual void pause();
|
||||
|
||||
/**
|
||||
* @brief Called when the widget resumes from a paused state
|
||||
* @details This method is invoked when the widget transitions from paused
|
||||
* to active state, typically after a previous pause() call. Derived
|
||||
* classes can override this method to restore animations, reload
|
||||
* resources, or continue interrupted operations.
|
||||
*
|
||||
* @note The base implementation is empty, allowing derived classes to override
|
||||
* only if resume behavior is needed.
|
||||
* @note This method should restore the widget to the state it was in before pause() was called.
|
||||
*/
|
||||
virtual void resume();
|
||||
|
||||
/**
|
||||
* @brief Called when the widget is being destroyed or exits the system
|
||||
* @details This method is invoked when the widget is about to be removed
|
||||
* from the system or transitions to an inactive state permanently.
|
||||
* Derived classes can override this method to perform cleanup tasks,
|
||||
* save final state, or release resources that are not automatically freed.
|
||||
*
|
||||
* @note The base implementation is empty, allowing derived classes to override
|
||||
* only if exit behavior is needed.
|
||||
* @note This method is called before the widget's destructor and provides
|
||||
* an opportunity for controlled shutdown of widget-specific resources.
|
||||
*/
|
||||
virtual void exit();
|
||||
|
||||
/**
|
||||
|
||||
@@ -1,36 +1,397 @@
|
||||
/**
|
||||
* @file ScreenSaver.h
|
||||
* @brief Animated screensaver implementation with starfield effect
|
||||
* @details This header defines the ScreenSaver class which provides an animated
|
||||
* starfield screensaver that activates during periods of user inactivity.
|
||||
* The screensaver displays moving stars to prevent screen burn-in while
|
||||
* providing visual feedback that the system is still active and responsive.
|
||||
* @author System Control Team
|
||||
* @date 2025-06-14
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "MenuOptions.h"
|
||||
#include "common/Widget.h"
|
||||
#include <vector>
|
||||
|
||||
/**
|
||||
* @class ScreenSaver
|
||||
* @brief Animated starfield screensaver widget for system idle periods
|
||||
* @details This final class inherits from Widget and implements an interactive
|
||||
* screensaver featuring an animated starfield effect. The screensaver
|
||||
* activates automatically during periods of user inactivity to prevent
|
||||
* screen burn-in while maintaining visual indication of system activity.
|
||||
*
|
||||
* The ScreenSaver class provides:
|
||||
* - Dynamic starfield animation with pseudo-3D depth effect
|
||||
* - Configurable star count and animation speed parameters
|
||||
* - Automatic activation during idle periods
|
||||
* - Immediate deactivation on any user input
|
||||
* - Smooth star movement and regeneration system
|
||||
* - Memory-efficient star management with object pooling
|
||||
*
|
||||
* Key features include:
|
||||
* - 3D-style starfield with depth-based speed variation
|
||||
* - Continuous star recycling for infinite animation
|
||||
* - Responsive user input handling for immediate exit
|
||||
* - Optimized rendering for smooth animation performance
|
||||
* - Configurable animation parameters for different visual effects
|
||||
*
|
||||
* The starfield effect simulates movement through space by moving stars
|
||||
* from the center outward at speeds proportional to their depth (z-coordinate).
|
||||
* Stars that move beyond the screen boundaries are automatically recycled
|
||||
* to new random positions, creating an infinite scrolling effect.
|
||||
*
|
||||
* @note This class is marked as final and cannot be inherited from.
|
||||
* @note The screensaver automatically exits on any button press, returning
|
||||
* control to the previous screen or main menu interface.
|
||||
*
|
||||
* @see Widget for base widget functionality
|
||||
* @see menu_options_t for configuration structure
|
||||
* @see InactivityTracker for automatic screensaver activation
|
||||
*/
|
||||
class ScreenSaver final : public Widget
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* @brief Constructs the screensaver with specified configuration
|
||||
* @param options Pointer to menu options configuration structure
|
||||
*
|
||||
* @pre options must not be nullptr and must remain valid for the screensaver's lifetime
|
||||
* @pre options->u8g2 must be initialized and ready for graphics operations
|
||||
* @pre Screen transition callbacks in options must be properly configured
|
||||
* @post ScreenSaver is initialized with starfield ready for animation
|
||||
*
|
||||
* @details The constructor initializes the screensaver by:
|
||||
* - Setting up the star field with initial random positions
|
||||
* - Configuring animation timing and speed parameters
|
||||
* - Preparing graphics context for efficient rendering
|
||||
* - Initializing the animation counter for smooth timing
|
||||
* - Allocating and positioning all star objects
|
||||
*
|
||||
* During initialization, all stars are placed at random positions within
|
||||
* the 3D space defined by Z_NEAR and Z_FAR constants. Each star receives
|
||||
* random x, y coordinates and a z-depth that determines its movement speed
|
||||
* and visual appearance. The animation system is prepared for immediate
|
||||
* activation when the screensaver becomes active.
|
||||
*
|
||||
* @note The screensaver does not take ownership of the options structure
|
||||
* and assumes it remains valid throughout the screensaver's lifetime.
|
||||
* @note Initial star positions are randomized to create immediate visual
|
||||
* interest when the screensaver first activates.
|
||||
*
|
||||
* @see Widget::Widget for base class construction details
|
||||
* @see initStars for star field initialization process
|
||||
*/
|
||||
explicit ScreenSaver(menu_options_t *options);
|
||||
|
||||
/**
|
||||
* @brief Updates the screensaver animation and star positions
|
||||
* @param dt Delta time in milliseconds since the last update call
|
||||
*
|
||||
* @details Overrides the base Widget update method to handle screensaver-specific
|
||||
* animation logic including:
|
||||
* - Advancing the animation counter for smooth timing control
|
||||
* - Updating individual star positions based on their speed and depth
|
||||
* - Moving stars outward from center based on their z-coordinate
|
||||
* - Recycling stars that move beyond screen boundaries
|
||||
* - Maintaining consistent animation frame rate regardless of system load
|
||||
*
|
||||
* The update method implements the core starfield animation by:
|
||||
* - Incrementing each star's position based on its depth-determined speed
|
||||
* - Checking boundary conditions for stars moving off-screen
|
||||
* - Resetting off-screen stars to new random positions near the center
|
||||
* - Applying speed multipliers for smooth, consistent motion
|
||||
* - Managing the animation counter for timing-dependent effects
|
||||
*
|
||||
* Star movement calculation:
|
||||
* - Stars closer to the camera (smaller z values) move faster
|
||||
* - Movement speed is inversely proportional to z-coordinate
|
||||
* - Stars maintain consistent outward direction from screen center
|
||||
* - Boundary checking ensures smooth recycling without visual gaps
|
||||
*
|
||||
* @note This method is called every frame while the screensaver is active
|
||||
* and must be efficient to maintain smooth 60+ FPS animation.
|
||||
* @note The animation continues indefinitely until user input is received.
|
||||
*
|
||||
* @see Widget::update for the base update interface
|
||||
* @see resetStar for star recycling implementation
|
||||
*/
|
||||
void update(uint64_t dt) override;
|
||||
|
||||
/**
|
||||
* @brief Renders the animated starfield to the display
|
||||
*
|
||||
* @details Overrides the base Widget render method to draw the animated starfield
|
||||
* effect. The rendering process includes:
|
||||
* - Clearing the display buffer for clean animation frames
|
||||
* - Calculating screen positions for each star based on 3D coordinates
|
||||
* - Applying perspective projection to simulate depth
|
||||
* - Drawing stars with size/brightness based on distance
|
||||
* - Optimizing drawing operations for smooth frame rates
|
||||
*
|
||||
* The render method creates a convincing 3D starfield effect by:
|
||||
* - Converting 3D star coordinates to 2D screen positions
|
||||
* - Scaling star positions based on perspective projection
|
||||
* - Varying star appearance (size, brightness) based on depth
|
||||
* - Drawing only stars within the visible screen area
|
||||
* - Using efficient drawing primitives for optimal performance
|
||||
*
|
||||
* Rendering optimizations include:
|
||||
* - Culling stars outside the visible area
|
||||
* - Using simple pixel/point drawing for maximum speed
|
||||
* - Minimizing graphics context switches
|
||||
* - Batching drawing operations where possible
|
||||
*
|
||||
* The visual effect simulates movement through a star field by:
|
||||
* - Making distant stars appear smaller and dimmer
|
||||
* - Scaling star positions relative to screen center
|
||||
* - Creating smooth motion blur effects for fast-moving stars
|
||||
*
|
||||
* @pre u8g2 display context must be initialized and ready for drawing
|
||||
* @post Starfield animation frame is drawn to the display buffer
|
||||
*
|
||||
* @note This method is called every frame and must be highly optimized
|
||||
* to maintain smooth animation performance on embedded systems.
|
||||
* @note The visual design provides an engaging screensaver that clearly
|
||||
* indicates system activity while preventing screen burn-in.
|
||||
*
|
||||
* @see Widget::render for the base render interface
|
||||
*/
|
||||
void render() override;
|
||||
|
||||
/**
|
||||
* @brief Handles user input to exit the screensaver immediately
|
||||
* @param button The type of button that was pressed by the user
|
||||
*
|
||||
* @details Overrides the base Widget button handling to provide immediate
|
||||
* screensaver exit functionality. Any button press while the screensaver
|
||||
* is active will:
|
||||
* - Immediately terminate the screensaver animation
|
||||
* - Return to the previous screen or main menu
|
||||
* - Reset any inactivity timers to prevent immediate reactivation
|
||||
* - Ensure responsive system behavior for user interaction
|
||||
*
|
||||
* The method handles all button types uniformly since the screensaver should
|
||||
* exit on any user input regardless of the specific button pressed. This
|
||||
* ensures maximum responsiveness and intuitive behavior - users expect any
|
||||
* interaction to wake the system from screensaver mode.
|
||||
*
|
||||
* Button handling includes:
|
||||
* - Immediate screensaver termination regardless of button type
|
||||
* - Automatic transition back to the previous active screen
|
||||
* - Inactivity timer reset to prevent immediate screensaver reactivation
|
||||
* - Proper state cleanup to ensure system stability
|
||||
*
|
||||
* @note This method ensures the screensaver never interferes with normal
|
||||
* system operation - any user input immediately restores full functionality.
|
||||
* @note The screensaver exit process is designed to be instantaneous to
|
||||
* provide the most responsive user experience possible.
|
||||
*
|
||||
* @see Widget::onButtonClicked for the base input handling interface
|
||||
* @see ButtonType for available button input types
|
||||
*/
|
||||
void onButtonClicked(ButtonType button) override;
|
||||
|
||||
private:
|
||||
/**
|
||||
* @struct Star
|
||||
* @brief Individual star object structure for starfield animation
|
||||
* @details Defines the properties and state of a single star in the animated
|
||||
* starfield. Each star maintains its position in 3D space and movement
|
||||
* characteristics needed for realistic animation and perspective effects.
|
||||
*
|
||||
* The Star structure contains:
|
||||
* - 3D spatial coordinates (x, y, z) for position tracking
|
||||
* - Individual speed multiplier for varied animation effects
|
||||
* - All data needed for perspective projection and movement calculation
|
||||
*
|
||||
* Star coordinate system:
|
||||
* - x, y: Screen-relative coordinates (can be negative for off-screen positioning)
|
||||
* - z: Depth coordinate determining speed and perspective (Z_NEAR to Z_FAR range)
|
||||
* - speed: Individual multiplier for varied star movement rates
|
||||
*
|
||||
* @note This structure is designed for efficient memory usage and fast
|
||||
* mathematical operations during animation updates.
|
||||
* @note All coordinates use float precision for smooth animation interpolation.
|
||||
*/
|
||||
struct Star
|
||||
{
|
||||
float x;
|
||||
float y;
|
||||
float z;
|
||||
float speed;
|
||||
float x; ///< Horizontal position coordinate (screen-relative)
|
||||
float y; ///< Vertical position coordinate (screen-relative)
|
||||
float z; ///< Depth coordinate (determines speed and perspective)
|
||||
float speed; ///< Individual speed multiplier for animation variation
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief Pointer to menu options configuration structure
|
||||
* @details Stores a reference to the menu configuration passed during construction.
|
||||
* Provides access to the display context for rendering operations and
|
||||
* screen transition callbacks for exiting the screensaver on user input.
|
||||
*
|
||||
* The configuration enables:
|
||||
* - Display context (u8g2) for starfield graphics rendering
|
||||
* - Screen transition callbacks for returning to previous screen
|
||||
* - System integration for proper screensaver lifecycle management
|
||||
*
|
||||
* @note This pointer is not owned by the ScreenSaver and must remain valid
|
||||
* throughout the screensaver's lifetime.
|
||||
*/
|
||||
menu_options_t *m_options;
|
||||
|
||||
/**
|
||||
* @brief Animation timing counter for smooth frame rate control
|
||||
* @details Tracks elapsed time for animation timing and frame rate calculations.
|
||||
* Used to ensure consistent star movement regardless of system load
|
||||
* variations and to provide smooth interpolation between animation frames.
|
||||
*
|
||||
* The counter enables:
|
||||
* - Frame rate independent animation timing
|
||||
* - Smooth interpolation for fluid star movement
|
||||
* - Consistent animation speed across different hardware platforms
|
||||
* - Precise timing control for animation effects
|
||||
*/
|
||||
uint64_t m_animationCounter;
|
||||
|
||||
/**
|
||||
* @brief Vector container for all star objects in the starfield
|
||||
* @details Manages the collection of Star objects that comprise the animated
|
||||
* starfield effect. The vector provides efficient storage and iteration
|
||||
* for the star animation system while maintaining good cache locality
|
||||
* for optimal performance during update and render operations.
|
||||
*
|
||||
* The vector contains:
|
||||
* - Fixed number of Star objects (NUM_STARS) allocated at initialization
|
||||
* - Contiguous memory layout for efficient iteration during animation
|
||||
* - Dynamic management capabilities for potential future enhancements
|
||||
*
|
||||
* @note The vector size is fixed at construction to avoid memory allocations
|
||||
* during animation, ensuring consistent frame timing performance.
|
||||
*/
|
||||
std::vector<Star> m_stars;
|
||||
|
||||
/**
|
||||
* @brief Total number of stars in the animated starfield
|
||||
* @details Defines the constant number of star objects that will be created
|
||||
* and animated in the starfield effect. This value balances visual
|
||||
* richness with performance requirements for smooth animation.
|
||||
*
|
||||
* The star count affects:
|
||||
* - Visual density and richness of the starfield effect
|
||||
* - Performance requirements for update and rendering operations
|
||||
* - Memory usage for star object storage
|
||||
* - Overall visual impact of the screensaver
|
||||
*
|
||||
* @note This value is tuned for optimal performance on target hardware
|
||||
* while providing an engaging visual effect.
|
||||
*/
|
||||
static constexpr int NUM_STARS = 10;
|
||||
|
||||
/**
|
||||
* @brief Global speed multiplier for star animation
|
||||
* @details Controls the overall speed of star movement in the starfield animation.
|
||||
* This multiplier is applied to all star movement calculations to provide
|
||||
* consistent, smooth animation at an appropriate visual speed.
|
||||
*
|
||||
* The speed multiplier affects:
|
||||
* - Overall pace of the starfield animation
|
||||
* - Visual impact and engagement level of the screensaver
|
||||
* - Performance requirements for smooth animation
|
||||
* - User perception of system responsiveness
|
||||
*
|
||||
* @note This value is carefully tuned to provide engaging animation without
|
||||
* being distracting or causing motion sickness effects.
|
||||
*/
|
||||
static constexpr float SPEED_MULTIPLIER = 0.02f;
|
||||
|
||||
/**
|
||||
* @brief Near clipping plane for 3D starfield depth range
|
||||
* @details Defines the closest distance (minimum z-coordinate) at which stars
|
||||
* can exist in the 3D starfield space. Stars closer than this distance
|
||||
* are considered too close to the viewer and are recycled to new positions.
|
||||
*
|
||||
* The near plane affects:
|
||||
* - Minimum depth for star positioning and recycling
|
||||
* - Perspective calculation range for realistic depth effects
|
||||
* - Star recycling triggers for continuous animation
|
||||
* - Visual depth range of the starfield effect
|
||||
*
|
||||
* @note This value works with Z_FAR to define the 3D space within which
|
||||
* stars exist and animate, creating realistic depth perception.
|
||||
*/
|
||||
static constexpr float Z_NEAR = 0.1f;
|
||||
|
||||
/**
|
||||
* @brief Far clipping plane for 3D starfield depth range
|
||||
* @details Defines the farthest distance (maximum z-coordinate) at which stars
|
||||
* can exist in the 3D starfield space. This establishes the back
|
||||
* boundary of the starfield volume and affects initial star placement.
|
||||
*
|
||||
* The far plane affects:
|
||||
* - Maximum depth for initial star positioning
|
||||
* - Perspective calculation range for depth effects
|
||||
* - Visual depth range and scale of the starfield
|
||||
* - Initial star placement during system initialization
|
||||
*
|
||||
* @note This value works with Z_NEAR to create a realistic 3D space
|
||||
* that provides convincing depth perception in the starfield animation.
|
||||
*/
|
||||
static constexpr float Z_FAR = 10.0f;
|
||||
|
||||
/**
|
||||
* @brief Initializes all stars with random positions and properties
|
||||
* @details Private helper method that sets up the initial starfield by placing
|
||||
* all stars at random positions within the defined 3D space. Called
|
||||
* during construction to prepare the starfield for immediate animation.
|
||||
*
|
||||
* The initialization process:
|
||||
* - Assigns random x, y coordinates within screen boundaries
|
||||
* - Sets random z-depth within the Z_NEAR to Z_FAR range
|
||||
* - Configures individual speed multipliers for animation variation
|
||||
* - Ensures even distribution of stars throughout the 3D volume
|
||||
*
|
||||
* Random placement creates:
|
||||
* - Natural, non-uniform star distribution for realistic appearance
|
||||
* - Varied star depths for convincing 3D perspective effects
|
||||
* - Immediate visual interest when screensaver first activates
|
||||
* - Foundation for smooth continuous animation
|
||||
*
|
||||
* @note This method is called only once during construction to establish
|
||||
* the initial starfield state before animation begins.
|
||||
*
|
||||
* @see resetStar for individual star repositioning during animation
|
||||
*/
|
||||
void initStars();
|
||||
|
||||
/**
|
||||
* @brief Resets a single star to a new random position for recycling
|
||||
* @param star Reference to the Star object to be reset and repositioned
|
||||
*
|
||||
* @details Private helper method that recycles individual stars that have
|
||||
* moved beyond the visible screen boundaries. This enables infinite
|
||||
* starfield animation by continuously introducing new stars while
|
||||
* removing those that are no longer visible.
|
||||
*
|
||||
* The reset process:
|
||||
* - Places the star at a new random position near the screen center
|
||||
* - Assigns a new random depth (z-coordinate) for varied movement speed
|
||||
* - Configures new speed multiplier for animation variation
|
||||
* - Ensures smooth transition without visual discontinuities
|
||||
*
|
||||
* Star recycling maintains:
|
||||
* - Continuous starfield animation without visual gaps
|
||||
* - Consistent star count throughout animation lifecycle
|
||||
* - Varied star properties for natural, non-repetitive effects
|
||||
* - Efficient memory usage through object reuse
|
||||
*
|
||||
* @pre star parameter must be a valid Star object reference
|
||||
* @post star object is repositioned with new random properties ready for animation
|
||||
*
|
||||
* @note This method is called frequently during animation as stars move
|
||||
* off-screen and must be efficient to maintain smooth frame rates.
|
||||
* @note The repositioning algorithm ensures stars appear to emerge naturally
|
||||
* from the center of the starfield for convincing 3D movement effects.
|
||||
*/
|
||||
void resetStar(Star &star);
|
||||
};
|
||||
};
|
||||
Reference in New Issue
Block a user