---
name: "SDLmm_Surface"
section: "3"
platform: "linux"
package: "libsdl-mm0.1"
version: "0.1.8-4"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/SDLmm_Surface"
---

# SDLmm\_Surface(3)

A graphical surface structure which is used to store graphical data.

## NAME

SDLmm::Surface - A graphical surface structure which is used to store graphical data.

## SYNOPSIS

`#include <sdlmm_surface.h>`

Inherits **SDLmm::BaseSurface**.

### Public Methods

**Surface** (SDL\_Surface \*surface)\
 *Constructor from an SDL\_Surface\*.* **Surface** (const Surface &other)\
 **Surface** ()\
 *Create an uninitialized surface.* Surface& **operator=** (const Surface &other)\
 *Implementation of operator=.* Surface **Duplicate** () const\
 virtual bool **SetDisplayFormat** ()\
 *Convert the surface to the display format.* virtual bool **SetDisplayFormatAlpha** ()\
 *Convert the surface to the display format.*

### Static Public Methods

Surface **CreateSurface** (const **BaseSurface** &other)\
 Surface **CreateSurface** (Uint32 flags, int w, int h, int d, Uint32 Rmask=0, Uint32 Gmask=0, Uint32 Bmask=0, Uint32 Amask=0)\
 *Allocate an empty RGB surface.* Surface **CreateSurface** (void \*pixels, int w, int h, int d, int p, Uint32 Rmask=0, Uint32 Gmask=0, Uint32 Bmask=0, Uint32 Amask=0)\
 *Create a new* **Surface** *from the provided pixel data.* Surface **LoadBMP** (const char \*file)\
 *Loads a Windows BMP and returns it as a new* **Surface***.* Surface **LoadBMP** (const std::string &file)\
 *Loads a Windows BMP and returns a new* **Surface***.*

## DETAILED DESCRIPTION

A graphical surface structure which is used to store graphical data.

Surfaces represent areas of 'graphical' memory, memory that can be drawn to or blitted onto other Surfaces.

**Todo:**  **Implement a better constructor scheme, where the first argument is a dummy class which specified what to do. This would allow a construct where a surface can be loaded from an image file without first having to create an unitialized object.**

**Author:**  **David Hedbor \<david@hedbor.org\>**

## CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

### SDLmm::Surface::Surface (SDL\_Surface \* surface)` [inline, explicit]`

**Constructor from an SDL\_Surface\*.**

**This creates a new Surface object from an existing SDL\_Surface. It's very important not to free the original surface since that will cause a problem when the object is destructed (SDL\_Surface storage freed twice). Use with caution.**

### SDLmm::Surface::Surface (const Surface & other)` [inline]`

### SDLmm::Surface::Surface ()` [inline]`

**Create an uninitialized surface.**

**Warning:**  **Trying to use an uninitialized surface will result in crashes. Most functions to not have any checks to see whether the surface is initialized or not.**

## MEMBER FUNCTION DOCUMENTATION

### Surface SDLmm::Surface::CreateSurface (void \* pixels, int w, int h, int d, int p, Uint32 Rmask = 0, Uint32 Gmask = 0, Uint32 Bmask = 0, Uint32 Amask = 0)` [inline, static]`

**Create a new Surface from the provided pixel data.**

**The data stored in** *pixels* **is assumed to be of the depth specified in the parameter** *d***. The pixel data is not copied into the SDL\_Surface structure me so it should no be freed until the Surface object has been destructed**

**Parameters:**

- *flags*

  *the type of surface that should be created which is OR'd combination of the values as described in the SDL documentation.*

- *w, h*

  *width and height of the surface to create.*

- *d*

  *color depth in bits per pixel to use for this surface. If zero, use the depth of the current display.*

- *p*

  *pitch the length (pitch) of each scanline in bytes.*

- *RGBAmask*

  *optional binary masks used to retrieve individual color values.*

### Surface SDLmm::Surface::CreateSurface (Uint32 flags, int w, int h, int d, Uint32 Rmask = 0, Uint32 Gmask = 0, Uint32 Bmask = 0, Uint32 Amask = 0)` [inline, static]`

*Allocate an empty RGB surface.*

*If depth is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' SDL\_PixelFormat is created using the \[RGBA\]mask's provided. The flags specifies*

**Parameters:**

- *flags*

  *the type of surface that should be created which is OR'd combination of the values as described in the SDL documentation.*

- *w, h*

  *width and height of the surface to create.*

- *d*

  *color depth in bits per pixel to use for this surface. If zero, use the depth of the current display.*

- *RGBAmask*

  *optional binary masks used to retrieve individual color values.*

### Surface SDLmm::Surface::CreateSurface (const BaseSurface & other)` [inline, static]`

### Surface SDLmm::Surface::Duplicate () const` [inline]`

### Surface SDLmm::Surface::LoadBMP (const std::string & file)` [inline, static]`

*Loads a Windows BMP and returns a new* **Surface***.*

**Parameters:**

- *file*

  *the file to attempt to load*

**Returns:**  *True if the loading succeeded, false otherwise.*

### Surface SDLmm::Surface::LoadBMP (const char \* file)` [inline, static]`

*Loads a Windows BMP and returns it as a new* **Surface***.*

*If the image couldn't be loaded, the* **Surface** *will be invalid. You can check the success of the image loading using the Surface.valid() method like the example code below.*

```
      SDLmm::Surface img(SDLmm::Surface::LoadBMP('myimage.bmp'));
      if(!img.valid()) {
        cerr << 'Loading of image myimage.bmp failed!0;
        exit(1);
      }
```

**Parameters:**

- *file*

  *the file to attempt to load*

**Returns:**  *True if the loading succeeded, false otherwise.*

### bool SDLmm::Surface::SetDisplayFormat ()` [virtual]`

*Convert the surface to the display format.*

*This function converts the surface to the pixel format and colors of the video framebuffer, making it suitable for fast blitting onto the display surface.*

*If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.*

**Returns:**  *The functions returns true if the conversion succeeded or false otherwise. If the conversion failed, the* **BaseSurface** *object will not have changed.*

**Note:**  *Please note that this function doesn't return a new, modified object like the SDL\_DisplayFormat() function does. Thus there is no need to manually free the old surface.*

**See also:**  **SetDisplayFormatAlpha***(),* **SetAlpha***(),* **SetColorKey***()*

*Reimplemented from* **SDLmm::BaseSurface***.*

### bool SDLmm::Surface::SetDisplayFormatAlpha ()` [virtual]`

*Convert the surface to the display format.*

*This function converts the surface to the pixel format and colors of the video framebuffer plus an alpha channel, making it suitable for fast blitting onto the display surface.*

*If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.*

**Returns:**  *The functions returns true if the conversion succeeded or false otherwise. If the conversion failed, the* **BaseSurface** *object will not have changed.*

**Note:**  *Please note that this function doesn't return a new, modified object like the SDL\_DisplayFormatAlpha() function does. Thus there is no need to manually free the old surface.*

**See also:**  **SetDisplayFormat***(),* **SetAlpha***(),* **SetColorKey***()*

*Reimplemented from* **SDLmm::BaseSurface***.*

### Surface & SDLmm::Surface::operator= (const Surface & other)` [inline]`

*Implementation of operator=.*

## AUTHOR

*Generated automatically by Doxygen for SDLmm from the source code.*