From 44d4c4e70754166e5a5d65ce6ad752372668afcb Mon Sep 17 00:00:00 2001 From: Laurent Gomila Date: Tue, 31 Jan 2012 20:03:00 +0100 Subject: [PATCH] Updated comments of graphics classes --- include/SFML/Graphics/Color.h | 53 +++---- include/SFML/Graphics/Font.h | 58 +++---- include/SFML/Graphics/Glyph.h | 3 +- include/SFML/Graphics/Image.h | 291 +++++++++++++++++++++------------- include/SFML/Graphics/Rect.h | 16 +- include/SFML/Graphics/View.h | 139 ++++++++-------- src/SFML/Graphics/Color.cpp | 27 ++-- src/SFML/Graphics/Image.cpp | 62 ++------ src/SFML/Graphics/View.cpp | 75 ++------- 9 files changed, 349 insertions(+), 375 deletions(-) diff --git a/include/SFML/Graphics/Color.h b/include/SFML/Graphics/Color.h index 3b905c8..184ab8f 100644 --- a/include/SFML/Graphics/Color.h +++ b/include/SFML/Graphics/Color.h @@ -32,7 +32,8 @@ //////////////////////////////////////////////////////////// -/// sfColor is an utility class for manipulating colors +/// \brief Utility class for manpulating RGBA colors +/// //////////////////////////////////////////////////////////// typedef struct { @@ -43,25 +44,23 @@ typedef struct } sfColor; -//////////////////////////////////////////////////////////// -/// Define some common colors -//////////////////////////////////////////////////////////// -CSFML_API sfColor sfBlack; -CSFML_API sfColor sfWhite; -CSFML_API sfColor sfRed; -CSFML_API sfColor sfGreen; -CSFML_API sfColor sfBlue; -CSFML_API sfColor sfYellow; -CSFML_API sfColor sfMagenta; -CSFML_API sfColor sfCyan; +CSFML_API sfColor sfBlack; ///< Black predefined color +CSFML_API sfColor sfWhite; ///< White predefined color +CSFML_API sfColor sfRed; ///< Red predefined color +CSFML_API sfColor sfGreen; ///< Green predefined color +CSFML_API sfColor sfBlue; ///< Blue predefined color +CSFML_API sfColor sfYellow; ///< Yellow predefined color +CSFML_API sfColor sfMagenta; ///< Magenta predefined color +CSFML_API sfColor sfCyan; ///< Cyan predefined color +CSFML_API sfColor sfTransparent; ///< Transparent (black) predefined color //////////////////////////////////////////////////////////// -/// Construct a color from its 3 RGB components +/// \brief Construct a color from its 3 RGB components /// -/// \param red : Red component (0 .. 255) -/// \param green : Green component (0 .. 255) -/// \param blue : Blue component (0 .. 255) +/// \param red Red component (0 .. 255) +/// \param green Green component (0 .. 255) +/// \param blue Blue component (0 .. 255) /// /// \return sfColor constructed from the components /// @@ -69,12 +68,12 @@ CSFML_API sfColor sfCyan; CSFML_API sfColor sfColor_FromRGB(sfUint8 red, sfUint8 green, sfUint8 blue); //////////////////////////////////////////////////////////// -/// Construct a color from its 4 RGBA components +/// \brief Construct a color from its 4 RGBA components /// -/// \param red : Red component (0 .. 255) -/// \param green : Green component (0 .. 255) -/// \param blue : Blue component (0 .. 255) -/// \param alpha : Alpha component (0 .. 255) +/// \param red Red component (0 .. 255) +/// \param green Green component (0 .. 255) +/// \param blue Blue component (0 .. 255) +/// \param alpha Alpha component (0 .. 255) /// /// \return sfColor constructed from the components /// @@ -82,10 +81,10 @@ CSFML_API sfColor sfColor_FromRGB(sfUint8 red, sfUint8 green, sfUint8 blue); CSFML_API sfColor sfColor_FromRGBA(sfUint8 red, sfUint8 green, sfUint8 blue, sfUint8 alpha); //////////////////////////////////////////////////////////// -/// Add two colors +/// \brief Add two colors /// -/// \param color1 : First color -/// \param color2 : Second color +/// \param color1 First color +/// \param color2 Second color /// /// \return Component-wise saturated addition of the two colors /// @@ -93,10 +92,10 @@ CSFML_API sfColor sfColor_FromRGBA(sfUint8 red, sfUint8 green, sfUint8 blue, sfU CSFML_API sfColor sfColor_Add(sfColor color1, sfColor color2); //////////////////////////////////////////////////////////// -/// Modulate two colors +/// \brief Modulate two colors /// -/// \param color1 : First color -/// \param color2 : Second color +/// \param color1 First color +/// \param color2 Second color /// /// \return Component-wise multiplication of the two colors /// diff --git a/include/SFML/Graphics/Font.h b/include/SFML/Graphics/Font.h index 1e27c4c..bcb6b07 100644 --- a/include/SFML/Graphics/Font.h +++ b/include/SFML/Graphics/Font.h @@ -35,9 +35,9 @@ //////////////////////////////////////////////////////////// -/// Create a new font from a file +/// \brief Create a new font from a file /// -/// \param filename : Path of the font file to load +/// \param filename Path of the font file to load /// /// \return A new sfFont object, or NULL if it failed /// @@ -45,10 +45,10 @@ CSFML_API sfFont* sfFont_CreateFromFile(const char* filename); //////////////////////////////////////////////////////////// -/// Create a new image font a file in memory +/// \brief Create a new image font a file in memory /// -/// \param data : Pointer to the file data in memory -/// \param sizeInBytes : Size of the data to load, in bytes +/// \param data Pointer to the file data in memory +/// \param sizeInBytes Size of the data to load, in bytes /// /// \return A new sfFont object, or NULL if it failed /// @@ -56,9 +56,9 @@ CSFML_API sfFont* sfFont_CreateFromFile(const char* filename); CSFML_API sfFont* sfFont_CreateFromMemory(const void* data, size_t sizeInBytes); //////////////////////////////////////////////////////////// -/// Create a new image font a custom stream +/// \brief Create a new image font a custom stream /// -/// \param stream : Source stream to read from +/// \param stream Source stream to read from /// /// \return A new sfFont object, or NULL if it failed /// @@ -66,9 +66,9 @@ CSFML_API sfFont* sfFont_CreateFromMemory(const void* data, size_t sizeInBytes); CSFML_API sfFont* sfFont_CreateFromStream(sfInputStream* stream); //////////////////////////////////////////////////////////// -/// Copy an existing font +/// \brief Copy an existing font /// -/// \param font : Font to copy +/// \param font Font to copy /// /// \return Copied object /// @@ -76,20 +76,20 @@ CSFML_API sfFont* sfFont_CreateFromStream(sfInputStream* stream); CSFML_API sfFont* sfFont_Copy(sfFont* font); //////////////////////////////////////////////////////////// -/// Destroy an existing font +/// \brief Destroy an existing font /// -/// \param font : Font to delete +/// \param font Font to delete /// //////////////////////////////////////////////////////////// CSFML_API void sfFont_Destroy(sfFont* font); //////////////////////////////////////////////////////////// -/// Get a glyph in a font +/// \brief Get a glyph in a font /// -/// \param font : Source font -/// \param codePoint : Unicode code point of the character to get -/// \param characterSize : Character size, in pixels -/// \param bold Retrieve the bold version or the regular one? +/// \param font Source font +/// \param codePoint Unicode code point of the character to get +/// \param characterSize Character size, in pixels +/// \param bold Retrieve the bold version or the regular one? /// /// \return The corresponding glyph /// @@ -97,12 +97,12 @@ CSFML_API void sfFont_Destroy(sfFont* font); CSFML_API sfGlyph sfFont_GetGlyph(sfFont* font, sfUint32 codePoint, unsigned int characterSize, sfBool bold); //////////////////////////////////////////////////////////// -/// Get the kerning value corresponding to a given pair of characters in a font +/// \brief Get the kerning value corresponding to a given pair of characters in a font /// -/// \param font : Source font -/// \param first : Unicode code point of the first character -/// \param second : Unicode code point of the second character -/// \param characterSize : Character size, in pixels +/// \param font Source font +/// \param first Unicode code point of the first character +/// \param second Unicode code point of the second character +/// \param characterSize Character size, in pixels /// /// \return Kerning offset, in pixels /// @@ -110,11 +110,11 @@ CSFML_API sfGlyph sfFont_GetGlyph(sfFont* font, sfUint32 codePoint, unsigned int CSFML_API int sfFont_GetKerning(sfFont* font, sfUint32 first, sfUint32 second, unsigned int characterSize); //////////////////////////////////////////////////////////// -/// Get the line spacing value +/// \brief Get the line spacing value /// -/// \param font : Source font -/// \param codePoint : Unicode code point of the character to get -/// \param characterSize : Character size, in pixels +/// \param font Source font +/// \param codePoint Unicode code point of the character to get +/// \param characterSize Character size, in pixels /// /// \return Line spacing, in pixels /// @@ -122,10 +122,10 @@ CSFML_API int sfFont_GetKerning(sfFont* font, sfUint32 first, sfUint32 second, u CSFML_API int sfFont_GetLineSpacing(sfFont* font, unsigned int characterSize); //////////////////////////////////////////////////////////// -/// Get the texture containing the glyphs of a given size in a font +/// \brief Get the texture containing the glyphs of a given size in a font /// -/// \param font : Source font -/// \param characterSize : Character size, in pixels +/// \param font Source font +/// \param characterSize Character size, in pixels /// /// \return Read-only pointer to the texture /// @@ -133,7 +133,7 @@ CSFML_API int sfFont_GetLineSpacing(sfFont* font, unsigned int characterSize); CSFML_API const sfTexture* sfFont_GetTexture(sfFont* font, unsigned int characterSize); //////////////////////////////////////////////////////////// -/// Get the built-in default font (Arial) +/// \brief Get the built-in default font (Arial) /// /// \return Pointer to the default font /// diff --git a/include/SFML/Graphics/Glyph.h b/include/SFML/Graphics/Glyph.h index 8e1e0f4..e873c56 100644 --- a/include/SFML/Graphics/Glyph.h +++ b/include/SFML/Graphics/Glyph.h @@ -32,7 +32,8 @@ //////////////////////////////////////////////////////////// -/// sfGlyph describes a glyph (a visual character) +/// \brief sfGlyph describes a glyph (a visual character) +/// //////////////////////////////////////////////////////////// typedef struct { diff --git a/include/SFML/Graphics/Image.h b/include/SFML/Graphics/Image.h index 0ed9abf..8809dd9 100644 --- a/include/SFML/Graphics/Image.h +++ b/include/SFML/Graphics/Image.h @@ -37,64 +37,97 @@ //////////////////////////////////////////////////////////// -/// Create a new image filled with a color +/// \brief Create an image /// -/// \param width : Image width -/// \param height : Image height -/// \param color : Image color +/// This image is filled with black pixels. +/// +/// \param width Width of the image +/// \param height Height of the image +/// +/// \return A new sfImage object +/// +//////////////////////////////////////////////////////////// +sfImage* sfImage_Create(unsigned int width, unsigned int height); + +//////////////////////////////////////////////////////////// +/// \brief Create an image and fill it with a unique color +/// +/// \param width Width of the image +/// \param height Height of the image +/// \param color Fill color +/// +/// \return A new sfImage object +/// +//////////////////////////////////////////////////////////// +sfImage* sfImage_CreateFromColor(unsigned int width, unsigned int height, sfColor color); + +//////////////////////////////////////////////////////////// +/// \brief Create an image from an array of pixels +/// +/// The \a pixel array is assumed to contain 32-bits RGBA pixels, +/// and have the given \a width and \a height. If not, this is +/// an undefined behaviour. +/// If \a pixels is null, an empty image is created. +/// +/// \param width Width of the image +/// \param height Height of the image +/// \param pixels Array of pixels to copy to the image +/// +/// \return A new sfImage object +/// +//////////////////////////////////////////////////////////// +sfImage* sfImage_CreateFromPixels(unsigned int width, unsigned int height, const sfUint8* pixels); + +//////////////////////////////////////////////////////////// +/// \brief Create an image from a file on disk +/// +/// The supported image formats are bmp, png, tga, jpg, gif, +/// psd, hdr and pic. Some format options are not supported, +/// like progressive jpeg. +/// If this function fails, the image is left unchanged. +/// +/// \param filename Path of the image file to load /// /// \return A new sfImage object, or NULL if it failed /// //////////////////////////////////////////////////////////// -CSFML_API sfImage* sfImage_CreateFromColor(unsigned int width, unsigned int height, sfColor color); +sfImage* sfImage_CreateFromFile(const char* filename); //////////////////////////////////////////////////////////// -/// Create a new image from an array of pixels in memory +/// \brief Create an image from a file in memory /// -/// \param width : Image width -/// \param height : Image height -/// \param data : Pointer to the pixels in memory (assumed format is RGBA) +/// The supported image formats are bmp, png, tga, jpg, gif, +/// psd, hdr and pic. Some format options are not supported, +/// like progressive jpeg. +/// If this function fails, the image is left unchanged. +/// +/// \param data Pointer to the file data in memory +/// \param size Size of the data to load, in bytes /// /// \return A new sfImage object, or NULL if it failed /// //////////////////////////////////////////////////////////// -CSFML_API sfImage* sfImage_CreateFromPixels(unsigned int width, unsigned int height, const sfUint8* data); +sfImage* sfImage_CreateFromMemory(const void* data, size_t size); //////////////////////////////////////////////////////////// -/// Create a new image from a file +/// \brief Create an image from a custom stream /// -/// \param filename : Path of the image file to load +/// The supported image formats are bmp, png, tga, jpg, gif, +/// psd, hdr and pic. Some format options are not supported, +/// like progressive jpeg. +/// If this function fails, the image is left unchanged. +/// +/// \param stream Source stream to read from /// /// \return A new sfImage object, or NULL if it failed /// //////////////////////////////////////////////////////////// -CSFML_API sfImage* sfImage_CreateFromFile(const char* filename); +sfImage* sfImage_CreateFromStream(sfInputStream* stream); //////////////////////////////////////////////////////////// -/// Create a new image from a file in memory +/// \brief Copy an existing image /// -/// \param data : Pointer to the file data in memory -/// \param sizeInBytes : Size of the data to load, in bytes -/// -/// \return A new sfImage object, or NULL if it failed -/// -//////////////////////////////////////////////////////////// -CSFML_API sfImage* sfImage_CreateFromMemory(const void* data, size_t sizeInBytes); - -//////////////////////////////////////////////////////////// -/// Create a new image from a custom stream -/// -/// \param stream : Source stream to read from -/// -/// \return A new sfImage object, or NULL if it failed -/// -//////////////////////////////////////////////////////////// -CSFML_API sfImage* sfImage_CreateFromStream(sfInputStream* stream); - -//////////////////////////////////////////////////////////// -/// Copy an existing image -/// -/// \param image : Image to copy +/// \param image Image to copy /// /// \return Copied object /// @@ -102,119 +135,149 @@ CSFML_API sfImage* sfImage_CreateFromStream(sfInputStream* stream); CSFML_API sfImage* sfImage_Copy(sfImage* image); //////////////////////////////////////////////////////////// -/// Destroy an existing image +/// \brief Destroy an existing image /// -/// \param image : Image to delete +/// \param image Image to delete /// //////////////////////////////////////////////////////////// CSFML_API void sfImage_Destroy(sfImage* image); //////////////////////////////////////////////////////////// -/// Save the content of an image to a file +/// \brief Save an image to a file on disk /// -/// \param image : Image to save -/// \param filename : Path of the file to save (overwritten if already exist) +/// The format of the image is automatically deduced from +/// the extension. The supported image formats are bmp, png, +/// tga and jpg. The destination file is overwritten +/// if it already exists. This function fails if the image is empty. +/// +/// \param image Image object +/// \param filename Path of the file to save /// /// \return sfTrue if saving was successful /// //////////////////////////////////////////////////////////// -CSFML_API sfBool sfImage_SaveToFile(const sfImage* image, const char* filename); +sfBool sfImage_SaveToFile(const sfImage* image, const char* filename); //////////////////////////////////////////////////////////// -/// Create a transparency mask for an image from a specified colorkey +/// \brief Return the width of an image /// -/// \param image : Image to modify -/// \param colorKey : Color to become transparent -/// \param alpha : Alpha value to use for transparent pixels -/// -//////////////////////////////////////////////////////////// -CSFML_API void sfImage_CreateMaskFromColor(sfImage* image, sfColor colorKey, sfUint8 alpha); - -//////////////////////////////////////////////////////////// -/// Copy pixels from another image onto this one. -/// This function does a slow pixel copy and should only -/// be used at initialization time -/// -/// \param image : Destination image -/// \param source : Source image to copy -/// \param destX : X coordinate of the destination position -/// \param destY : Y coordinate of the destination position -/// \param sourceRect : Sub-rectangle of the source image to copy -/// \param applyAlpha : Should the copy take in account the source transparency? -/// -//////////////////////////////////////////////////////////// -CSFML_API void sfImage_CopyImage(sfImage* image, const sfImage* source, unsigned int destX, unsigned int destY, sfIntRect sourceRect, sfBool applyAlpha); - -//////////////////////////////////////////////////////////// -/// Change the color of a pixel of an image -/// -/// \param image : Image to modify -/// \param x : X coordinate of pixel in the image -/// \param y : Y coordinate of pixel in the image -/// \param color : New color for pixel (X, Y) -/// -//////////////////////////////////////////////////////////// -CSFML_API void sfImage_SetPixel(sfImage* image, unsigned int x, unsigned int y, sfColor color); - -//////////////////////////////////////////////////////////// -/// Get a pixel from an image -/// -/// \param image : Image to read -/// \param x : X coordinate of pixel in the image -/// \param y : Y coordinate of pixel in the image -/// -/// \return Color of pixel (x, y) -/// -//////////////////////////////////////////////////////////// -CSFML_API sfColor sfImage_GetPixel(const sfImage* image, unsigned int x, unsigned int y); - -//////////////////////////////////////////////////////////// -/// Get a read-only pointer to the array of pixels of an image (8 bits integers RGBA) -/// Array size is sfImage_GetWidth(img) x sfImage_GetHeight(img) x 4 -/// This pointer becomes invalid if you reload or resize the image -/// -/// \param image : Image to read -/// -/// \return Pointer to the array of pixels -/// -//////////////////////////////////////////////////////////// -CSFML_API const sfUint8* sfImage_GetPixelsPtr(const sfImage* image); - -//////////////////////////////////////////////////////////// -/// Return the width of the image -/// -/// \param image : Image to read +/// \param image Image object /// /// \return Width in pixels /// //////////////////////////////////////////////////////////// -CSFML_API unsigned int sfImage_GetWidth(const sfImage* image); +unsigned int sfImage_GetWidth(const sfImage* image); //////////////////////////////////////////////////////////// -/// Return the height of the image +/// \brief Return the height of an image /// -/// \param image : Image to read +/// \param image Image object /// /// \return Height in pixels /// //////////////////////////////////////////////////////////// -CSFML_API unsigned int sfImage_GetHeight(const sfImage* image); +unsigned int sfImage_GetHeight(const sfImage* image); //////////////////////////////////////////////////////////// -/// Flip an image horizontally (left <-> right) +/// \brief Create a transparency mask from a specified color-key /// -/// \param image : Image to flip +/// This function sets the alpha value of every pixel matching +/// the given color to \a alpha (0 by default), so that they +/// become transparent. +/// +/// \param image Image object +/// \param color Color to make transparent +/// \param alpha Alpha value to assign to transparent pixels /// //////////////////////////////////////////////////////////// -CSFML_API void sfImage_FlipHorizontally(sfImage* image); +void sfImage_CreateMaskFromColor(sfColor color, sfUint8 alpha); //////////////////////////////////////////////////////////// -/// Flip an image vertically (top <-> bottom) +/// \brief Copy pixels from an image onto another /// -/// \param image : Image to flip +/// This function does a slow pixel copy and should not be +/// used intensively. It can be used to prepare a complex +/// static image from several others, but if you need this +/// kind of feature in real-time you'd better use sfRenderTexture. +/// +/// If \a sourceRect is empty, the whole image is copied. +/// If \a applyAlpha is set to true, the transparency of +/// source pixels is applied. If it is false, the pixels are +/// copied unchanged with their alpha value. +/// +/// \param image Image object +/// \param source Source image to copy +/// \param destX X coordinate of the destination position +/// \param destY Y coordinate of the destination position +/// \param sourceRect Sub-rectangle of the source image to copy +/// \param applyAlpha Should the copy take in account the source transparency? /// //////////////////////////////////////////////////////////// -CSFML_API void sfImage_FlipVertically(sfImage* image); +void sfImage_CopyImage(sfImage* image, const sfImage* source, unsigned int destX, unsigned int destY, sfIntRect sourceRect, sfBool applyAlpha); + +//////////////////////////////////////////////////////////// +/// \brief Change the color of a pixel in an image +/// +/// This function doesn't check the validity of the pixel +/// coordinates, using out-of-range values will result in +/// an undefined behaviour. +/// +/// \param image Image object +/// \param x X coordinate of pixel to change +/// \param y Y coordinate of pixel to change +/// \param color New color of the pixel +/// +//////////////////////////////////////////////////////////// +void sfImage_SetPixel(sfImage* image, unsigned int x, unsigned int y, sfColor color); + +//////////////////////////////////////////////////////////// +/// \brief Get the color of a pixel in an image +/// +/// This function doesn't check the validity of the pixel +/// coordinates, using out-of-range values will result in +/// an undefined behaviour. +/// +/// \param image Image object +/// \param x X coordinate of pixel to get +/// \param y Y coordinate of pixel to get +/// +/// \return Color of the pixel at coordinates (x, y) +/// +//////////////////////////////////////////////////////////// +sfColor sfImage_GetPixel(const sfImage* image, unsigned int x, unsigned int y); + +//////////////////////////////////////////////////////////// +/// \brief Get a read-only pointer to the array of pixels of an image +/// +/// The returned value points to an array of RGBA pixels made of +/// 8 bits integers components. The size of the array is +/// GetWidth() * GetHeight() * 4. +/// Warning: the returned pointer may become invalid if you +/// modify the image, so you should never store it for too long. +/// If the image is empty, a null pointer is returned. +/// +/// \param image Image object +/// +/// \return Read-only pointer to the array of pixels +/// +//////////////////////////////////////////////////////////// +const sfUint8* sfImage_GetPixelsPtr(const sfImage* image); + +//////////////////////////////////////////////////////////// +/// \brief Flip an image horizontally (left <-> right) +/// +/// \param image Image object +/// +//////////////////////////////////////////////////////////// +void sfImage_FlipHorizontally(sfImage* image); + +//////////////////////////////////////////////////////////// +/// \brief Flip an image vertically (top <-> bottom) +/// +/// \param image Image object +/// +//////////////////////////////////////////////////////////// +void sfImage_FlipVertically(sfImage* image); #endif // SFML_IMAGE_H diff --git a/include/SFML/Graphics/Rect.h b/include/SFML/Graphics/Rect.h index b9a3a31..623ae68 100644 --- a/include/SFML/Graphics/Rect.h +++ b/include/SFML/Graphics/Rect.h @@ -52,11 +52,11 @@ typedef struct } sfIntRect; //////////////////////////////////////////////////////////// -/// Check if a point is inside a rectangle's area +/// \brief Check if a point is inside a rectangle's area /// -/// \param rect : Rectangle to test -/// \param x : X coordinate of the point to test -/// \param y : Y coordinate of the point to test +/// \param rect Rectangle to test +/// \param x X coordinate of the point to test +/// \param y Y coordinate of the point to test /// /// \return sfTrue if the point is inside /// @@ -65,11 +65,11 @@ CSFML_API sfBool sfFloatRect_Contains(const sfFloatRect* rect, float x, float y) CSFML_API sfBool sfIntRect_Contains(const sfIntRect* rect, int x, int y); //////////////////////////////////////////////////////////// -/// Check intersection between two rectangles +/// \brief Check intersection between two rectangles /// -/// \param rect1 : First rectangle to test -/// \param rect2 : Second rectangle to test -/// \param intersection : Rectangle to be filled with overlapping rect (can be NULL) +/// \param rect1 First rectangle to test +/// \param rect2 Second rectangle to test +/// \param intersection Rectangle to be filled with overlapping rect (can be NULL) /// /// \return sfTrue if rectangles overlap /// diff --git a/include/SFML/Graphics/View.h b/include/SFML/Graphics/View.h index 9ba811a..88d3c4a 100644 --- a/include/SFML/Graphics/View.h +++ b/include/SFML/Graphics/View.h @@ -34,23 +34,29 @@ //////////////////////////////////////////////////////////// -/// Construct a default view (1000x1000) +/// \brief Create a default view +/// +/// This function creates a default view of (0, 0, 1000, 1000) +/// +/// \return A new sfView object /// //////////////////////////////////////////////////////////// CSFML_API sfView* sfView_Create(void); //////////////////////////////////////////////////////////// -/// Construct a view from a rectangle +/// \brief Construct a view from a rectangle /// -/// \param rectangle : Rectangle defining the bounds of the view +/// \param rectangle Rectangle defining the zone to display +/// +/// \return A new sfView object /// //////////////////////////////////////////////////////////// CSFML_API sfView* sfView_CreateFromRect(sfFloatRect rectangle); //////////////////////////////////////////////////////////// -/// Copy an existing view +/// \brief Copy an existing view /// -/// \param view : View to copy +/// \param view View to copy /// /// \return Copied object /// @@ -58,119 +64,105 @@ CSFML_API sfView* sfView_CreateFromRect(sfFloatRect rectangle); CSFML_API sfView* sfView_Copy(sfView* view); //////////////////////////////////////////////////////////// -/// Destroy an existing view +/// \brief Destroy an existing view /// -/// \param view : View to destroy +/// \param view View to destroy /// //////////////////////////////////////////////////////////// CSFML_API void sfView_Destroy(sfView* view); //////////////////////////////////////////////////////////// -/// Change the center of a view +/// \brief Set the center of a view /// -/// \param view : View to modify -/// \param x : X coordinate of the new center -/// \param y : Y coordinate of the new center +/// \param view View object +/// \param x X coordinate of the new center +/// \param y Y coordinate of the new center /// //////////////////////////////////////////////////////////// CSFML_API void sfView_SetCenter(sfView* view, float x, float y); //////////////////////////////////////////////////////////// -/// Change the size of a view +/// \brief Set the size of a view /// -/// \param view : View to modify -/// \param width : New width -/// \param height : New height +/// \param view View object +/// \param width New width of the view +/// \param height New height of the view /// //////////////////////////////////////////////////////////// CSFML_API void sfView_SetSize(sfView* view, float width, float height); //////////////////////////////////////////////////////////// -/// Set the angle of rotation of a view +/// \brief Set the orientation of a view /// -/// \param view : View to modify -/// \param angle : New angle, in degrees +/// The default rotation of a view is 0 degree. +/// +/// \param view View object +/// \param angle New angle, in degrees /// //////////////////////////////////////////////////////////// CSFML_API void sfView_SetRotation(sfView* view, float angle); //////////////////////////////////////////////////////////// -/// Set the target viewport of a view +/// \brief Set the target viewport of a view /// /// The viewport is the rectangle into which the contents of the /// view are displayed, expressed as a factor (between 0 and 1) /// of the size of the RenderTarget to which the view is applied. +/// For example, a view which takes the left side of the target would +/// be defined by a rect of (0, 0, 0.5, 1). +/// By default, a view has a viewport which covers the entire target. /// -/// \param view : View to modify -/// \param viewport : New viewport +/// \param view View object +/// \param viewport New viewport rectangle /// //////////////////////////////////////////////////////////// CSFML_API void sfView_SetViewport(sfView* view, sfFloatRect viewport); //////////////////////////////////////////////////////////// -/// Reset a view to the given rectangle. -/// Note: this function resets the rotation angle to 0. +/// \brief Reset a view to the given rectangle /// -/// \param view : View to modify -/// \param rectangle : Rectangle defining the position and size of the view +/// Note that this function resets the rotation angle to 0. +/// +/// \param view View object +/// \param rectangle Rectangle defining the zone to display /// //////////////////////////////////////////////////////////// CSFML_API void sfView_Reset(sfView* view, sfFloatRect rectangle); //////////////////////////////////////////////////////////// -/// Get the X coordinate of the center of a view +/// \brief Get the center of a view /// -/// \param view : View to read -/// -/// \return X coordinate of the center of the view +/// \param view View object +/// \param x Returned X coordinate of the center +/// \param y Returned Y coordinate of the center /// //////////////////////////////////////////////////////////// -CSFML_API float sfView_GetCenterX(const sfView* view); +CSFML_API void sfView_GetCenter(const sfView* view, float* x, float* y); //////////////////////////////////////////////////////////// -/// Get the Y coordinate of the center of a view +/// \brief Get the size of a view /// -/// \param view : View to read -/// -/// \return Y coordinate of the center of the view +/// \param view View object +/// \param width Returned width +/// \param height Returned height /// //////////////////////////////////////////////////////////// -CSFML_API float sfView_GetCenterY(const sfView* view); +CSFML_API void sfView_GetSize(const sfView* view, float* width, float* height); //////////////////////////////////////////////////////////// -/// Get the width of the view +/// \brief Get the current orientation of a view /// -/// \param view : View to read +/// \param view View object /// -/// \return Width of the view -/// -//////////////////////////////////////////////////////////// -CSFML_API float sfView_GetWidth(const sfView* view); - -//////////////////////////////////////////////////////////// -/// Get the height of the view -/// -/// \param view : View to read -/// -/// \return Height of the view -/// -//////////////////////////////////////////////////////////// -CSFML_API float sfView_GetHeight(const sfView* view); - -//////////////////////////////////////////////////////////// -/// Get the current rotation of a view -/// -/// \param view : View to read -/// -/// \return Rotation of the view, in degrees +/// \return Rotation angle of the view, in degrees /// //////////////////////////////////////////////////////////// CSFML_API float sfView_GetRotation(const sfView* view); //////////////////////////////////////////////////////////// -/// Get the target viewport of a view +/// \brief Get the target viewport rectangle of a view /// -/// \param view : View to read +/// \param view View object /// /// \return Viewport rectangle, expressed as a factor of the target size /// @@ -178,29 +170,36 @@ CSFML_API float sfView_GetRotation(const sfView* view); CSFML_API sfFloatRect sfView_GetViewport(const sfView* view); //////////////////////////////////////////////////////////// -/// Move a view +/// \brief Move a view relatively to its current position /// -/// \param view : View to move -/// \param offsetX : Offset to move the view, on X axis -/// \param offsetY : Offset to move the view, on Y axis +/// \param view View object +/// \param offsetX X coordinate of the move offset +/// \param offsetY Y coordinate of the move offset /// //////////////////////////////////////////////////////////// CSFML_API void sfView_Move(sfView* view, float offsetX, float offsetY); //////////////////////////////////////////////////////////// -/// Rotate a view +/// \brief Rotate a view relatively to its current orientation /// -/// \param view : View to rotate -/// \param angle : Angle in degrees +/// \param view View object +/// \param angle Angle to rotate, in degrees /// //////////////////////////////////////////////////////////// CSFML_API void sfView_Rotate(sfView* view, float angle); //////////////////////////////////////////////////////////// -/// Resize a view rectangle to simulate a zoom / unzoom effect +/// \brief Resize a view rectangle relatively to its current size /// -/// \param view : View to zoom -/// \param factor : Zoom factor to apply, relative to the current zoom +/// Resizing the view simulates a zoom, as the zone displayed on +/// screen grows or shrinks. +/// \a factor is a multiplier: +/// \li 1 keeps the size unchanged +/// \li > 1 makes the view bigger (objects appear smaller) +/// \li < 1 makes the view smaller (objects appear bigger) +/// +/// \param view View object +/// \param factor Zoom factor to apply /// //////////////////////////////////////////////////////////// CSFML_API void sfView_Zoom(sfView* view, float factor); diff --git a/src/SFML/Graphics/Color.cpp b/src/SFML/Graphics/Color.cpp index 6ff2009..b830198 100644 --- a/src/SFML/Graphics/Color.cpp +++ b/src/SFML/Graphics/Color.cpp @@ -31,20 +31,17 @@ //////////////////////////////////////////////////////////// -/// Define some common colors -//////////////////////////////////////////////////////////// -sfColor sfBlack = sfColor_FromRGB( 0, 0, 0); -sfColor sfWhite = sfColor_FromRGB(255, 255, 255); -sfColor sfRed = sfColor_FromRGB(255, 0, 0); -sfColor sfGreen = sfColor_FromRGB( 0, 255, 0); -sfColor sfBlue = sfColor_FromRGB( 0, 0, 255); -sfColor sfYellow = sfColor_FromRGB(255, 255, 0); -sfColor sfMagenta = sfColor_FromRGB(255, 0, 255); -sfColor sfCyan = sfColor_FromRGB( 0, 255, 255); +sfColor sfBlack = sfColor_FromRGB( 0, 0, 0); +sfColor sfWhite = sfColor_FromRGB(255, 255, 255); +sfColor sfRed = sfColor_FromRGB(255, 0, 0); +sfColor sfGreen = sfColor_FromRGB( 0, 255, 0); +sfColor sfBlue = sfColor_FromRGB( 0, 0, 255); +sfColor sfYellow = sfColor_FromRGB(255, 255, 0); +sfColor sfMagenta = sfColor_FromRGB(255, 0, 255); +sfColor sfCyan = sfColor_FromRGB( 0, 255, 255); +sfColor sfTransparent = sfColor_FromRGBA( 0, 0, 0, 0); -//////////////////////////////////////////////////////////// -/// Construct a color from its 3 RGB components //////////////////////////////////////////////////////////// sfColor sfColor_FromRGB(sfUint8 red, sfUint8 green, sfUint8 blue) { @@ -52,8 +49,6 @@ sfColor sfColor_FromRGB(sfUint8 red, sfUint8 green, sfUint8 blue) } -//////////////////////////////////////////////////////////// -/// Construct a color from its 4 RGBA components //////////////////////////////////////////////////////////// sfColor sfColor_FromRGBA(sfUint8 red, sfUint8 green, sfUint8 blue, sfUint8 alpha) { @@ -68,8 +63,6 @@ sfColor sfColor_FromRGBA(sfUint8 red, sfUint8 green, sfUint8 blue, sfUint8 alpha } -//////////////////////////////////////////////////////////// -/// Add two colors //////////////////////////////////////////////////////////// sfColor sfColor_Add(sfColor color1, sfColor color2) { @@ -85,8 +78,6 @@ sfColor sfColor_Add(sfColor color1, sfColor color2) } -//////////////////////////////////////////////////////////// -/// Modulate two colors //////////////////////////////////////////////////////////// sfColor sfColor_Modulate(sfColor color1, sfColor color2) { diff --git a/src/SFML/Graphics/Image.cpp b/src/SFML/Graphics/Image.cpp index 1cb1246..91c9740 100644 --- a/src/SFML/Graphics/Image.cpp +++ b/src/SFML/Graphics/Image.cpp @@ -30,9 +30,16 @@ #include #include - //////////////////////////////////////////////////////////// -/// Create a new image filled with a color +sfImage* sfImage_Create(unsigned int width, unsigned int height) +{ + sfImage* image = new sfImage; + image->This.Create(width, height); + + return image; +} + + //////////////////////////////////////////////////////////// sfImage* sfImage_CreateFromColor(unsigned int width, unsigned int height, sfColor color) { @@ -43,8 +50,6 @@ sfImage* sfImage_CreateFromColor(unsigned int width, unsigned int height, sfColo } -//////////////////////////////////////////////////////////// -/// Create a new image from an array of pixels in memory //////////////////////////////////////////////////////////// sfImage* sfImage_CreateFromPixels(unsigned int width, unsigned int height, const sfUint8* data) { @@ -55,8 +60,6 @@ sfImage* sfImage_CreateFromPixels(unsigned int width, unsigned int height, const } -//////////////////////////////////////////////////////////// -/// Create a new image from a file //////////////////////////////////////////////////////////// sfImage* sfImage_CreateFromFile(const char* filename) { @@ -72,8 +75,6 @@ sfImage* sfImage_CreateFromFile(const char* filename) } -//////////////////////////////////////////////////////////// -/// Create a new image from a file in memory //////////////////////////////////////////////////////////// sfImage* sfImage_CreateFromMemory(const void* data, size_t sizeInBytes) { @@ -89,8 +90,6 @@ sfImage* sfImage_CreateFromMemory(const void* data, size_t sizeInBytes) } -//////////////////////////////////////////////////////////// -/// Create a new image from a custom stream //////////////////////////////////////////////////////////// sfImage* sfImage_CreateFromStream(sfInputStream* stream) { @@ -109,8 +108,6 @@ sfImage* sfImage_CreateFromStream(sfInputStream* stream) } -//////////////////////////////////////////////////////////// -/// Copy an existing image //////////////////////////////////////////////////////////// sfImage* sfImage_Copy(sfImage* image) { @@ -120,8 +117,6 @@ sfImage* sfImage_Copy(sfImage* image) } -//////////////////////////////////////////////////////////// -/// Destroy an existing image //////////////////////////////////////////////////////////// void sfImage_Destroy(sfImage* image) { @@ -129,8 +124,6 @@ void sfImage_Destroy(sfImage* image) } -//////////////////////////////////////////////////////////// -/// Save the content of an image to a file //////////////////////////////////////////////////////////// sfBool sfImage_SaveToFile(const sfImage* image, const char* filename) { @@ -138,58 +131,41 @@ sfBool sfImage_SaveToFile(const sfImage* image, const char* filename) } -//////////////////////////////////////////////////////////// -/// Create a transparency mask for an image from a specified colorkey //////////////////////////////////////////////////////////// void sfImage_CreateMaskFromColor(sfImage* image, sfColor colorKey, sfUint8 alpha) { - sf::Color SFMLColor(colorKey.r, colorKey.g, colorKey.b, colorKey.a); - CSFML_CALL(image, CreateMaskFromColor(SFMLColor, alpha)); + CSFML_CALL(image, CreateMaskFromColor(sf::Color(colorKey.r, colorKey.g, colorKey.b, colorKey.a), alpha)); } -//////////////////////////////////////////////////////////// -/// Copy pixels from another image onto this one. -/// This function does a slow pixel copy and should only -/// be used at initialization time //////////////////////////////////////////////////////////// void sfImage_CopyImage(sfImage* image, const sfImage* source, unsigned int destX, unsigned int destY, sfIntRect sourceRect, sfBool applyAlpha) { CSFML_CHECK(source); - sf::IntRect SFMLRect(sourceRect.Left, sourceRect.Top, sourceRect.Width, sourceRect.Height); - CSFML_CALL(image, Copy(source->This, destX, destY, SFMLRect, applyAlpha == sfTrue)); + sf::IntRect sfmlRect(sourceRect.Left, sourceRect.Top, sourceRect.Width, sourceRect.Height); + CSFML_CALL(image, Copy(source->This, destX, destY, sfmlRect, applyAlpha == sfTrue)); } -//////////////////////////////////////////////////////////// -/// Change the color of a pixel of an image -/// Don't forget to call Update when you end modifying pixels //////////////////////////////////////////////////////////// void sfImage_SetPixel(sfImage* image, unsigned int x, unsigned int y, sfColor color) { - sf::Color SFMLColor(color.r, color.g, color.b, color.a); - CSFML_CALL(image, SetPixel(x, y, SFMLColor)); + CSFML_CALL(image, SetPixel(x, y, sf::Color(color.r, color.g, color.b, color.a))); } -//////////////////////////////////////////////////////////// -/// Get a pixel from an image //////////////////////////////////////////////////////////// sfColor sfImage_GetPixel(const sfImage* image, unsigned int x, unsigned int y) { sfColor color = {0, 0, 0, 0}; CSFML_CHECK_RETURN(image, color); - sf::Color SFMLColor = image->This.GetPixel(x, y); + sf::Color sfmlColor = image->This.GetPixel(x, y); - return sfColor_FromRGBA(SFMLColor.r, SFMLColor.g, SFMLColor.b, SFMLColor.a); + return sfColor_FromRGBA(sfmlColor.r, sfmlColor.g, sfmlColor.b, sfmlColor.a); } -//////////////////////////////////////////////////////////// -/// Get a read-only pointer to the array of pixels of an image (8 bits integers RGBA) -/// Array size is sfImage_GetWidth() x sfImage_GetHeight() x 4 -/// This pointer becomes invalid if you reload or resize the image //////////////////////////////////////////////////////////// const sfUint8* sfImage_GetPixelsPtr(const sfImage* image) { @@ -197,8 +173,6 @@ const sfUint8* sfImage_GetPixelsPtr(const sfImage* image) } -//////////////////////////////////////////////////////////// -/// Return the width of the image //////////////////////////////////////////////////////////// unsigned int sfImage_GetWidth(const sfImage* image) { @@ -206,8 +180,6 @@ unsigned int sfImage_GetWidth(const sfImage* image) } -//////////////////////////////////////////////////////////// -/// Return the height of the image //////////////////////////////////////////////////////////// unsigned int sfImage_GetHeight(const sfImage* image) { @@ -215,8 +187,6 @@ unsigned int sfImage_GetHeight(const sfImage* image) } -//////////////////////////////////////////////////////////// -/// Flip an image horizontally (left <-> right) //////////////////////////////////////////////////////////// void sfImage_FlipHorizontally(sfImage* image) { @@ -224,8 +194,6 @@ void sfImage_FlipHorizontally(sfImage* image) } -//////////////////////////////////////////////////////////// -/// Flip an image vertically (top <-> bottom) //////////////////////////////////////////////////////////// void sfImage_FlipVertically(sfImage* image) { diff --git a/src/SFML/Graphics/View.cpp b/src/SFML/Graphics/View.cpp index 573af0f..ec994dc 100644 --- a/src/SFML/Graphics/View.cpp +++ b/src/SFML/Graphics/View.cpp @@ -30,8 +30,6 @@ #include -//////////////////////////////////////////////////////////// -/// Construct a default view (1000x1000) //////////////////////////////////////////////////////////// sfView* sfView_Create(void) { @@ -39,8 +37,6 @@ sfView* sfView_Create(void) } -//////////////////////////////////////////////////////////// -/// Construct a view from a rectangle //////////////////////////////////////////////////////////// sfView* sfView_CreateFromRect(sfFloatRect rectangle) { @@ -51,8 +47,6 @@ sfView* sfView_CreateFromRect(sfFloatRect rectangle) } -//////////////////////////////////////////////////////////// -/// Copy an existing view //////////////////////////////////////////////////////////// sfView* sfView_Copy(sfView* view) { @@ -62,8 +56,6 @@ sfView* sfView_Copy(sfView* view) } -//////////////////////////////////////////////////////////// -/// Destroy an existing view //////////////////////////////////////////////////////////// void sfView_Destroy(sfView* view) { @@ -71,8 +63,6 @@ void sfView_Destroy(sfView* view) } -//////////////////////////////////////////////////////////// -/// Change the center of a view //////////////////////////////////////////////////////////// void sfView_SetCenter(sfView* view, float x, float y) { @@ -80,8 +70,6 @@ void sfView_SetCenter(sfView* view, float x, float y) } -//////////////////////////////////////////////////////////// -/// Change the size of a view //////////////////////////////////////////////////////////// void sfView_SetSize(sfView* view, float width, float height) { @@ -89,8 +77,6 @@ void sfView_SetSize(sfView* view, float width, float height) } -//////////////////////////////////////////////////////////// -/// Set the angle of rotation of a view //////////////////////////////////////////////////////////// void sfView_SetRotation(sfView* view, float angle) { @@ -98,8 +84,6 @@ void sfView_SetRotation(sfView* view, float angle) } -//////////////////////////////////////////////////////////// -/// Set the target viewport of a view //////////////////////////////////////////////////////////// void sfView_SetViewport(sfView* view, sfFloatRect viewport) { @@ -107,9 +91,6 @@ void sfView_SetViewport(sfView* view, sfFloatRect viewport) } -//////////////////////////////////////////////////////////// -/// Reset a view to the given rectangle. -/// Note: this function resets the rotation angle to 0. //////////////////////////////////////////////////////////// void sfView_Reset(sfView* view, sfFloatRect rectangle) { @@ -118,51 +99,31 @@ void sfView_Reset(sfView* view, sfFloatRect rectangle) //////////////////////////////////////////////////////////// -/// Get the X coordinate of the center of a view -//////////////////////////////////////////////////////////// -float sfView_GetCenterX(const sfView* view) +void sfView_GetCenter(const sfView* view, float* x, float* y) { - CSFML_CHECK_RETURN(view, 0.f); + CSFML_CHECK(view); - return view->This.GetCenter().x; + sf::Vector2f center = view->This.GetCenter(); + if (x) + *x = center.x; + if (y) + *y = center.y; } //////////////////////////////////////////////////////////// -/// Get the Y coordinate of the center of a view -//////////////////////////////////////////////////////////// -float sfView_GetCenterY(const sfView* view) +void sfView_GetSize(const sfView* view, float* width, float* height) { - CSFML_CHECK_RETURN(view, 0.f); + CSFML_CHECK(view); - return view->This.GetCenter().y; + sf::Vector2f size = view->This.GetSize(); + if (width) + *width = size.x; + if (height) + *height = size.y; } -//////////////////////////////////////////////////////////// -/// Get the width of the view -//////////////////////////////////////////////////////////// -float sfView_GetWidth(const sfView* view) -{ - CSFML_CHECK_RETURN(view, 0.f); - - return view->This.GetSize().x; -} - - -//////////////////////////////////////////////////////////// -/// Get the height of the view -//////////////////////////////////////////////////////////// -float sfView_GetHeight(const sfView* view) -{ - CSFML_CHECK_RETURN(view, 0.f); - - return view->This.GetSize().y; -} - - -//////////////////////////////////////////////////////////// -/// Get the current rotation of a view //////////////////////////////////////////////////////////// float sfView_GetRotation(const sfView* view) { @@ -170,8 +131,6 @@ float sfView_GetRotation(const sfView* view) } -//////////////////////////////////////////////////////////// -/// Get the target viewport of a view //////////////////////////////////////////////////////////// sfFloatRect sfView_GetViewport(const sfView* view) { @@ -188,8 +147,6 @@ sfFloatRect sfView_GetViewport(const sfView* view) } -//////////////////////////////////////////////////////////// -/// Move a view //////////////////////////////////////////////////////////// void sfView_Move(sfView* view, float offsetX, float offsetY) { @@ -197,8 +154,6 @@ void sfView_Move(sfView* view, float offsetX, float offsetY) } -//////////////////////////////////////////////////////////// -/// Rotate a view //////////////////////////////////////////////////////////// void sfView_Rotate(sfView* view, float angle) { @@ -206,8 +161,6 @@ void sfView_Rotate(sfView* view, float angle) } -//////////////////////////////////////////////////////////// -/// Resize a view rectangle to simulate a zoom / unzoom effect //////////////////////////////////////////////////////////// void sfView_Zoom(sfView* view, float factor) {