docs/man3/SDL_PixelFormat.3
author Sam Lantinga <slouken@libsdl.org>
Sat, 28 Jan 2006 05:47:11 +0000
changeset 1279 e867f327aa54
parent 181 e5bc29de3f0a
child 2283 546f7c1eb755
permissions -rw-r--r--
*** empty log message ***
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
     1
.TH "SDL_PixelFormat" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference" 
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     2
.SH "NAME"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     3
SDL_PixelFormat\- Stores surface format information
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     4
.SH "STRUCTURE DEFINITION"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     5
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     6
.nf
1279
e867f327aa54 *** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents: 181
diff changeset
     7
\f(CWtypedef struct SDL_PixelFormat {
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     8
  SDL_Palette *palette;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     9
  Uint8  BitsPerPixel;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    10
  Uint8  BytesPerPixel;
1279
e867f327aa54 *** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents: 181
diff changeset
    11
  Uint8  Rloss, Gloss, Bloss, Aloss;
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    12
  Uint8  Rshift, Gshift, Bshift, Ashift;
1279
e867f327aa54 *** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents: 181
diff changeset
    13
  Uint32 Rmask, Gmask, Bmask, Amask;
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    14
  Uint32 colorkey;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    15
  Uint8  alpha;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    16
} SDL_PixelFormat;\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    17
.fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    18
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    19
.SH "STRUCTURE DATA"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    20
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    21
\fBpalette\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    22
Pointer to the \fIpalette\fR, or \fBNULL\fP if the \fBBitsPerPixel\fR>8
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    23
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    24
\fBBitsPerPixel\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    25
The number of bits used to represent each pixel in a surface\&. Usually 8, 16, 24 or 32\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    26
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    27
\fBBytesPerPixel\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    28
The number of bytes used to represent each pixel in a surface\&. Usually one to four\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    29
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    30
\fB[RGBA]mask\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    31
Binary mask used to retrieve individual color values
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    32
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    33
\fB[RGBA]loss\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    34
Precision loss of each color component (2^[RGBA]loss)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    35
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    36
\fB[RGBA]shift\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    37
Binary left shift of each color component in the pixel value
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    38
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    39
\fBcolorkey\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    40
Pixel value of transparent pixels
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    41
.TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    42
\fBalpha\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    43
Overall surface alpha value
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    44
.SH "DESCRIPTION"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    45
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    46
A \fBSDL_PixelFormat\fR describes the format of the pixel data stored at the \fBpixels\fR field of a \fI\fBSDL_Surface\fR\fR\&. Every surface stores a \fBSDL_PixelFormat\fR in the \fBformat\fR field\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    47
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    48
If you wish to do pixel level modifications on a surface, then understanding how SDL stores its color information is essential\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    49
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    50
8-bit pixel formats are the easiest to understand\&. Since its an 8-bit format, we have 8 \fBBitsPerPixel\fR and 1 \fBBytesPerPixel\fR\&. Since \fBBytesPerPixel\fR is 1, all pixels are represented by a Uint8 which contains an index into \fBpalette\fR->\fBcolors\fR\&. So, to determine the color of a pixel in a 8-bit surface: we read the color index from \fBsurface\fR->\fBpixels\fR and we use that index to read the \fI\fBSDL_Color\fR\fR structure from \fBsurface\fR->\fBformat\fR->\fBpalette\fR->\fBcolors\fR\&. Like so: 
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    51
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    52
.nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    53
\f(CWSDL_Surface *surface;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    54
SDL_PixelFormat *fmt;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    55
SDL_Color *color;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    56
Uint8 index;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    57
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    58
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    59
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    60
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    61
/* Create surface */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    62
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    63
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    64
fmt=surface->format;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    65
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    66
/* Check the bitdepth of the surface */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    67
if(fmt->BitsPerPixel!=8){
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    68
  fprintf(stderr, "Not an 8-bit surface\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    69
");
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    70
  return(-1);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    71
}
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    72
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    73
/* Lock the surface */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    74
SDL_LockSurface(surface);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    75
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    76
/* Get the topleft pixel */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    77
index=*(Uint8 *)surface->pixels;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    78
color=fmt->palette->colors[index];
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    79
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    80
/* Unlock the surface */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    81
SDL_UnlockSurface(surface);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    82
printf("Pixel Color-> Red: %d, Green: %d, Blue: %d\&. Index: %d
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    83
",
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    84
          color->r, color->g, color->b, index);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    85
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    86
\&.\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    87
.fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    88
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    89
.PP
55
55f1f1b3e27d Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    90
Pixel formats above 8-bit are an entirely different experience\&. They are considered to be "TrueColor" formats and the color information is stored in the pixels themselves, not in a palette\&. The mask, shift and loss fields tell us how the color information is encoded\&. The mask fields allow us to isolate each color component, the shift fields tell us the number of bits to the right of each component in the pixel value and the loss fields tell us the number of bits lost from each component when packing 8-bit color component in a pixel\&. 
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    91
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    92
.nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    93
\f(CW/* Extracting color components from a 32-bit color value */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    94
SDL_PixelFormat *fmt;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    95
SDL_Surface *surface;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    96
Uint32 temp, pixel;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    97
Uint8 red, green, blue, alpha;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    98
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    99
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   100
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   101
fmt=surface->format;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   102
SDL_LockSurface(surface);
55
55f1f1b3e27d Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   103
pixel=*((Uint32*)surface->pixels);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   104
SDL_UnlockSurface(surface);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   105
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   106
/* Get Red component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   107
temp=pixel&fmt->Rmask; /* Isolate red component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   108
temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   109
temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   110
red=(Uint8)temp;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   111
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   112
/* Get Green component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   113
temp=pixel&fmt->Gmask; /* Isolate green component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   114
temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   115
temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   116
green=(Uint8)temp;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   117
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   118
/* Get Blue component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   119
temp=pixel&fmt->Bmask; /* Isolate blue component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   120
temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   121
temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   122
blue=(Uint8)temp;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   123
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   124
/* Get Alpha component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   125
temp=pixel&fmt->Amask; /* Isolate alpha component */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   126
temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   127
temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   128
alpha=(Uint8)temp;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   129
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   130
printf("Pixel Color -> R: %d,  G: %d,  B: %d,  A: %d
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   131
", red, green, blue, alpha);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   132
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   133
\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   134
\&.\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   135
.fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   136
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   137
.SH "SEE ALSO"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   138
.PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   139
\fI\fBSDL_Surface\fR\fR, \fI\fBSDL_MapRGB\fP\fR
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
   140
...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01