From 6de027f198e56947d89694049020de0893d374fc Mon Sep 17 00:00:00 2001
From: Jan Haller <bromeon@gmail.com>
Date: Sat, 23 May 2015 15:15:14 +0200
Subject: [PATCH] Clarified lifetime requirements of underlying resources for
 Music and Font

---
 include/SFML/Audio/Music.hpp   | 24 ++++++++++++++++--------
 include/SFML/Graphics/Font.hpp | 14 ++++++++++++--
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/include/SFML/Audio/Music.hpp b/include/SFML/Audio/Music.hpp
index a50272445..76b4254eb 100644
--- a/include/SFML/Audio/Music.hpp
+++ b/include/SFML/Audio/Music.hpp
@@ -69,6 +69,10 @@ public:
     /// See the documentation of sf::InputSoundFile for the list
     /// of supported formats.
     ///
+    /// \warning Since the music is not loaded at once but rather
+    /// streamed continuously, the file must remain accessible until
+    /// the sf::Music object loads a new music or is destroyed.
+    ///
     /// \param filename Path of the music file to open
     ///
     /// \return True if loading succeeded, false if it failed
@@ -85,10 +89,11 @@ public:
     /// to do so).
     /// See the documentation of sf::InputSoundFile for the list
     /// of supported formats.
-    /// Since the music is not loaded completely but rather streamed
-    /// continuously, the \a data must remain available as long as the
-    /// music is playing (i.e. you can't deallocate it right after calling
-    /// this function).
+    ///
+    /// \warning Since the music is not loaded at once but rather streamed
+    /// continuously, the \a data buffer must remain accessible until
+    /// the sf::Music object loads a new music or is destroyed. That is,
+    /// you can't deallocate the buffer right after calling this function.
     ///
     /// \param data        Pointer to the file data in memory
     /// \param sizeInBytes Size of the data to load, in bytes
@@ -107,10 +112,10 @@ public:
     /// to do so).
     /// See the documentation of sf::InputSoundFile for the list
     /// of supported formats.
-    /// Since the music is not loaded completely but rather streamed
-    /// continuously, the \a stream must remain alive as long as the
-    /// music is playing (i.e. you can't destroy it right after calling
-    /// this function).
+    ///
+    /// \warning Since the music is not loaded at once but rather
+    /// streamed continuously, the \a stream must remain accessible
+    /// until the sf::Music object loads a new music or is destroyed.
     ///
     /// \param stream Source stream to read from
     ///
@@ -184,6 +189,9 @@ private:
 /// musics that usually take hundreds of MB when they are
 /// uncompressed: by streaming it instead of loading it entirely,
 /// you avoid saturating the memory and have almost no loading delay.
+/// This implies that the underlying resource (file, stream or
+/// memory buffer) must remain valid for the lifetime of the
+/// sf::Music object.
 ///
 /// Apart from that, a sf::Music has almost the same features as
 /// the sf::SoundBuffer / sf::Sound pair: you can play/pause/stop
diff --git a/include/SFML/Graphics/Font.hpp b/include/SFML/Graphics/Font.hpp
index 9d7c68417..2b19d3987 100644
--- a/include/SFML/Graphics/Font.hpp
+++ b/include/SFML/Graphics/Font.hpp
@@ -95,6 +95,10 @@ public:
     /// fonts installed on the user's system, thus you can't
     /// load them directly.
     ///
+    /// \warning SFML cannot preload all the font data in this
+    /// function, so the file has to remain accessible until
+    /// the sf::Font object loads a new font or is destroyed.
+    ///
     /// \param filename Path of the font file to load
     ///
     /// \return True if loading succeeded, false if it failed
@@ -109,9 +113,11 @@ public:
     ///
     /// The supported font formats are: TrueType, Type 1, CFF,
     /// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
-    /// Warning: SFML cannot preload all the font data in this
+    ///
+    /// \warning SFML cannot preload all the font data in this
     /// function, so the buffer pointed by \a data has to remain
-    /// valid as long as the font is used.
+    /// valid until the sf::Font object loads a new font or
+    /// is destroyed.
     ///
     /// \param data        Pointer to the file data in memory
     /// \param sizeInBytes Size of the data to load, in bytes
@@ -132,6 +138,10 @@ public:
     /// function, so the contents of \a stream have to remain
     /// valid as long as the font is used.
     ///
+    /// \warning SFML cannot preload all the font data in this
+    /// function, so the stream has to remain accessible until
+    /// the sf::Font object loads a new font or is destroyed.
+    ///
     /// \param stream Source stream to read from
     ///
     /// \return True if loading succeeded, false if it failed