---
name: "SDL::Surface"
section: "3pm"
platform: "linux"
package: "libsdl-perl"
version: "2.548-5+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL::Surface"
---

# SDL::Surface(3pm)

Graphic surface structure

## NAME

SDL::Surface - Graphic surface structure

## CATEGORY

Core, Video, Structure

## SYNOPSIS

```
 use SDL;
 use SDL::Video;
 use SDL::Surface;
 # Create the main surface (display)
 SDL::init(SDL_INIT_VIDEO);
 my $display = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
 # Create other surfaces attached to the $display.
 my $surface  = SDL::Surface->new(SDL_ASYNCBLIT | SDL_HWSURFACE, 640, 480, 16, 0, 0, 0, 0);
 my $surface2 = SDL::Surface->new_from($surface, 100, 100, 8, 0, 0, 0, 0);
```

## DESCRIPTION

An `"SDL_Surface"` defines a surfaceangular area of pixels.

## CONSTANTS

The constants for SDL::Surface belong to SDL::Video, under the export tag of `':surface'`.

- SDL\_ASYNCBLIT

  Use asynchronous blit if possible

- SDL\_SWSURFACE

  Store in system memory

- SDL\_HWSURFACE

  Store in video memory

## METHODS

### new

```
 my $surface = SDL::Surface->new(
     $flags, $width, $height, $depth, $Rmask, $Gmask, $Bmask, $Amask
 );
```

The constructor creates a new surface with the specified parameter values.

The four mask values are the bits that the channel will ignore. For example, an Rmask of `0xFF` will ignore that channel completely, making everything on the surface more green/blue.

### new\_from

```
 my $surface = SDL::Surface->new_from(
     $surface, $width, $height, $depth, $Rmask, $Gmask, $Bmask, $Amask
 );
```

The constructor creates a new surface with the specified parameter values. The flags are taken from the specified `$surface`.

### w

```
 my $w = $surface->w;
```

Returns the width of the surface. SDL::Surface width is defined at construction so this is read-only.

### h

```
 my $h = $surface->h;
```

Returns the height of the surface. SDL::Surface height is defined at construction so this is read-only.

### format

```
 my $format = $surface->format;
```

The format of the pixels stored in the surface. See SDL::PixelFormat

### pitch

```
 my $pitch = $surface->pitch;
```

The scanline length in bytes.

## Direct Write to Surface Pixel

**Disclaimer:** The following methods can be very slow, making them suitable for creating surfaces, but not for animations

### get\_pixel

```
 my $pixel = $surface->get_pixel( $offset )
```

Returns the numeric pixel value for the given `$offset`. The pixel value depends on current pixel format.

**Note:** For surfaces with a palette (1 byte per pixel) the palette index is returned instead of color values.

### set\_pixels

```
 $surface->set_pixels( $offset, $value );
```

Sets the pixel `$value` to the given `$offset`. The pixel value must fit the pixel format of the surface.

**Note**: For surfaces with a palette (1 byte per pixel) the palette index must be passed instead of color values.

Example:

```
 sub putpixel {
     my ($x, $y, $color) = @_;
     $display->set_pixels( $x + $y * $display->w, $color);
 }
```

See also *examples/pixel\_operations/sols/ch02.pl*!

### get\_pixels\_ptr

```
 my $ptr = $surface->get_pixels_ptr;
```

Returns a reference to the surface's pixels.

## SEE ALSO

SDL, SDL::PixelFormat, SDL::Video, SDL::Rect

## AUTHORS

See "AUTHORS" in SDL.