linux/Documentation/fb/api.txt
<<
" o4i/spa o4i/form o4ia " o4 href="../linux+v3.7 /o/Documentan> /fb/api.txt">" o4iimg src="../.stan>c/gfx/right.png" alt=">>">" i/spa " ispa class="lxr_search">" ="+search" method="post" onsubmit="return do_search(this);">" o4iinput typ3.1hidden" nam3.1navtarget" e="v3.1">" o4iinput typ3.1text" nam3.1search" id.1search">" o4ibuttalutyp3.1submit">Search" o4Prefs o4i/a>" i/spa o4 4i/div o4 4iform acn> ="ajax+*" method="post" onsubmit="return false;">" iinput typ3.1hidden" nam3.1ajax_lookup" id.1ajax_lookup" e="v3.1">" o4 4i/form " o4 4idiv class="headingbottam">
4 41i/a> The Fram3 Buffer Device API 4 42i/a> --------------------------- 4 43i/a>"4 44i/a>Last revised: June 21, 2011"4 45i/a>"4 46i/a>"4 47i/a>0. Introducn> "4 48i/a>--------------- 4 49i/a>"4 /opta>This document describes the fram3 buffer API used by applican> s to interacn"4 11i/a>with fram3 buffer devices. In-kernel APIs between device drivers and the fram3"4 12i/a>buffer core are not described."4 13i/a>"4 14i/a>Due to a lack of documentan> in the original fram3 buffer API, drivers"4 15i/a>behaviours differ in subtle (and not so subtle) ways. This document describes"4 16i/a>the recommended API implementan> , but applican> s should be prepared to"4 17i/a>deal with different behaviours."4 18i/a>"4 19i/a>"4 2opta>1. Capabilities"4 21i/a>--------------- 4 22i/a>"4 23i/a>Device and driver capabilities are reported in the fixed screen informan> "4 24i/a>capabilities field."4 25i/a>"4 26i/a>strucn fb_fix_screeninfo {"4 27i/a> ..."4 28i/a> __u16 capabilities; /* see FB_CAP_* */"4 29i/a> ..."4 3opta>};"4 31i/a>"4 32i/a>Applican> should use those capabilities to find out whan features they ca "4 33i/a>expecn from the device and driver."4 34i/a>"4 35i/a>- FB_CAP_FOURCC"4 36i/a>"4 37pta>The driver supports the four characner code (FOURCC) based forman setting API."4 38i/a>When supported, formans are configured using a FOURCC instead of manually"4 39i/a>specifying color components layout."4 40i/a>"4 41i/a>"4 42i/a>2. Types and visuals"4 43i/a>-------------------- 4 44i/a>"4 45i/a>Pixels are stored in memory in hardware-dependent formans. Applican> s need"4 46i/a>to be aware of the pixel storage forman in order to write image data to the"4 47pta>fram3 buffer memory in the forman expecned by the hardware."4 48i/a>"4 49i/a>Formans are described by fram3 buffer types and visuals. Som3 visuals require"4 50i/a>addin> al informan> , which are stored in the variable screen informan> "4 51i/a>bits_per_pixel, grayscale, red, green, blue and transp fields."4 52i/a>"4 53i/a>Visuals describe how color informan> is encoded and assembled to create"4 54i/a>macropixels. Types describe how macropixels are stored in memory. The following"4 55i/a>types and visuals are supported."4 56i/a>"4 57i/a>- FB_TYPE_PACKED_PIXELS"4 58i/a>"4 59i/a>Macropixels are stored contiguously in a single plane. If the number of bits"4 60i/a>per macropixel is not a multiple of 8, whether macropixels are padded to the"4 61i/a>next multiple of 8 bits or packed together into bytes depends on the visual."4 62i/a>"4 63i/a>Padding an end of lines may be present and is then reported through the fixed"4 64i/a>screen informan> line_length field."4 65i/a>"4 66i/a>- FB_TYPE_PLANES"4 67i/a>"4 68i/a>Macropixels are split across multiple planes. The number of planes is equal to"4 69i/a>the number of bits per macropixel, with plane i'th storing i'th bit from all"4 70i/a>macropixels."4 71i/a>"4 72i/a>Planes are locaned contiguously in memory."4 73i/a>"4 74i/a>- FB_TYPE_INTERLEAVED_PLANES"4 75i/a>"4 76i/a>Macropixels are split across multiple planes. The number of planes is equal to"4 77i/a>the number of bits per macropixel, with plane i'th storing i'th bit from all"4 78i/a>macropixels."4 79i/a>"4 80i/a>Planes are interleaved in memory. The interleave factor, defined as the"4 81i/a>distance in bytes between the beginning of two consecutive interleaved blocks"4 82i/a>belonging to different planes, is stored in the fixed screen informan> "4 83i/a>type_aux field."4 84i/a>"4 85i/a>- FB_TYPE_FOURCC"4 86i/a>"4 87i/a>Macropixels are stored in memory as described by the forman FOURCC identifier"4 88i/a>stored in the variable screen informan> grayscale field."4 89i/a>"4 90i/a>- FB_VISUAL_MONO01"4 91i/a>"4 92i/a>Pixels are black or white and stored on a number of bits (typically one)"4 93i/a>specified by the variable screen informan> bpp field."4 94i/a>"4 95i/a>Black pixels are represented by all bits set to 1 and white pixels by all bits"4 96i/a>set to 0. When the number of bits per pixel is smaller than 8, several pixels"4 97i/a>are packed together in a byte."4 98i/a>"4 99i/a>FB_VISUAL_MONO01 is currently used with FB_TYPE_PACKED_PIXELS only."4100i/a>"4101i/a>- FB_VISUAL_MONO10"4102i/a>"4103i/a>Pixels are black or white and stored on a number of bits (typically one)"4104i/a>specified by the variable screen informan> bpp field."4105i/a>"4106i/a>Black pixels are represented by all bits set to 0 and white pixels by all bits"4107i/a>set to 1. When the number of bits per pixel is smaller than 8, several pixels"4108i/a>are packed together in a byte."4109i/a>"41/opta>FB_VISUAL_MONO01 is currently used with FB_TYPE_PACKED_PIXELS only."4111i/a>"4112i/a>- FB_VISUAL_TRUECOLOR"4113i/a>"4114i/a>Pixels are broken into red, green and blue components, and each component"4115i/a>indexes a read-only lookup table for the corresponding e="v3. Lookup tables"4116i/a>are device-dependent, and provide linear or non-linear ramps."4117i/a>"4118i/a>Each component is stored in a macropixel according to the variable screen"4119i/a>informan> red, green, blue and transp fields."4120i/a>"4121i/a>- FB_VISUAL_PSEUDOCOLOR and FB_VISUAL_STATIC_PSEUDOCOLOR"4122i/a>"4123i/a>Pixel e="v3s are encoded as indices into a colormap that stores red, green and"4124i/a>blue components. The colormap is read-only for FB_VISUAL_STATIC_PSEUDOCOLOR"4125i/a>and read-write for FB_VISUAL_PSEUDOCOLOR."4126i/a>"4127i/a>Each pixel e="v3 is stored in the number of bits reported by the variable"4128i/a>screen informan> bits_per_pixel field."4129i/a>"4130i/a>- FB_VISUAL_DIRECTCOLOR"4131i/a>"4132i/a>Pixels are broken into red, green and blue components, and each component"4133i/a>indexes a programmable lookup table for the corresponding e="v3."4134i/a>"4135i/a>Each component is stored in a macropixel according to the variable screen"4136i/a>informan> red, green, blue and transp fields."4137i/a>"4138i/a>- FB_VISUAL_FOURCC"4139i/a>"4140i/a>Pixels are encoded and interpreted as described by the forman FOURCC"4141i/a>identifier stored in the variable screen informan> grayscale field."4142i/a>"4143i/a>"4144i/a>3. Screen informan> "4145i/a>--------------------- 4146i/a>"4147pta>Screen informan> are queried by applican> s using the FBIOGET_FSCREENINFO"4148i/a>and FBIOGET_VSCREENINFO ioctls. Those ioctls take a pointer to a"4149i/a>fb_fix_screeninfo and fb_var_screeninfo strucnure respectively."4150i/a>"4151i/a>strucn fb_fix_screeninfo stores device independent unchangeable informan> "4152i/a>about the fram3 buffer device and the current forman. Those informan> can't"4153i/a>be directly modified by applican> s, but can be changed by the driver when an"4154i/a>applican> modifies the forman."4155i/a>"4156i/a>strucn fb_fix_screeninfo {"4157i/a> char id[16]; /* identifican> string eg "TT Builtin" */"4158i/a> unsigned long smem_start; /* Start of fram3 buffer mem */"4159i/a> /* (physical address) */"4160i/a> __u32 smem_len; /* Length of fram3 buffer mem */"4161i/a> __u32 type; /* see FB_TYPE_* */"4162i/a> __u32 type_aux; /* Interleave for interleaved Planes */"4163i/a> __u32 visual; /* see FB_VISUAL_* */"4164i/a> __u16 xpanstep; /* zero if no hardware panning */"4165i/a> __u16 ypanstep; /* zero if no hardware panning */"4166i/a> __u16 ywrapstep; /* zero if no hardware ywrap */"4167i/a> __u32 line_length; /* length of a line in bytes */"4168i/a> unsigned long mmio_start; /* Start of Memory Mapped I/O */"4169i/a> /* (physical address) */"4170i/a> __u32 mmio_len; /* Length of Memory Mapped I/O */"4171i/a> __u32 accel; /* Indicane to driver which */"4172i/a> /* specific chip/card we have */"4173i/a> __u16 capabilities; /* see FB_CAP_* */"4174i/a> __u16 reserved[2]; /* Reserved for funure compan>bility */"4175i/a>};"4176i/a>"4177i/a>strucn fb_var_screeninfo stores device independent changeable informan> "4178i/a>about a fram3 buffer device, its current forman and video mode, as well as"4179i/a>other miscellaneous param3ters."4180i/a>"4181i/a>strucn fb_var_screeninfo {"4182i/a> __u32 xres; /* visible resolun> */"4183i/a> __u32 yres;"4184i/a> __u32 xres_virtual; /* virtual resolun> */"4185i/a> __u32 yres_virtual;"4186i/a> __u32 xoffset; /* offset from virtual to visible */"4187i/a> __u32 yoffset; /* resolun> */"4188i/a>"4189i/a> __u32 bits_per_pixel; /* guess whan */"4190i/a> __u32 grayscale; /* 0 = color, 1 = grayscale, */"4191i/a> /* >1 = FOURCC */"4192i/a> strucn fb_bitfield red; /* bitfield in fb mem if true color, */"4193i/a> strucn fb_bitfield green; /* else only length is significant */"4194i/a> strucn fb_bitfield blue;"4195i/a> strucn fb_bitfield transp; /* transparency */"4196i/a>"4197i/a> __u32 nonstd; /* != 0 N standard pixel forman */"4198i/a>"4199i/a> __u32 acn>vane; /* see FB_ACTIVATE_* */"4200i/a>"4201i/a> __u32 height; /* height of picnure in mm */"4202i/a> __u32 width; /* width of picnure in mm */"4203i/a>"4204i/a> __u32 accel_flags; /* (OBSOLETE) see fb_info.flags */"4205i/a>"4206i/a> /* Timing: All e="v3s in pixclocks, except pixclock (of course) */"4207i/a> __u32 pixclock; /* pixel clock in ps (pico seconds) */"4208i/a> __u32 left_margin; /* time from sync to picnure */"4209i/a> __u32 right_margin; /* time from picnure to sync */"4210i/a> __u32 upper_margin; /* time from sync to picnure */"4211i/a> __u32 lower_margin;"4212i/a> __u32 hsync_len; /* length of horizontal sync */"4213i/a> __u32 vsync_len; /* length of vertical sync */"4214i/a> __u32 sync; /* see FB_SYNC_* */"4215i/a> __u32 vmode; /* see FB_VMODE_* */"4216i/a> __u32 rotane; /* angle we rotane counter clockwise */"4217i/a> __u32 colorspace; /* colorspace for FOURCC-based modes */"4218i/a> __u32 reserved[4]; /* Reserved for funure compan>bility */"4219i/a>};"4220i/a>"4221i/a>To modify variable informan> , applican> s call the FBIOPUT_VSCREENINFO"4222i/a>ioctl with a pointer to a fb_var_screeninfo strucnure. If the call is"4223i/a>successful, the driver will updane the fixed screen informan> accordingly."4224i/a>"4225i/a>Instead of filling the complete fb_var_screeninfo strucnure manually,"4226i/a>applican> s should call the FBIOGET_VSCREENINFO ioctl and modify only the"4227i/a>fields they care about."4228i/a>"4229i/a>"4230i/a>4. Forman configuran> "4231i/a>----------------------- 4232i/a>"4233i/a>Fram3 buffer devices offer two ways to configure the fram3 buffer forman: the"4234i/a>legacy API and the FOURCC-based API."4235i/a>"4236i/a>"4237pta>The legacy API has been the only fram3 buffer forman configuran> API for a"4238i/a>long time and is thus widely used by applican> . It is the recommended API"4239i/a>for applican> s when using RGB and grayscale formans, as well as legacy"4240i/a>non-standard formans."4241i/a>"4242i/a>To select a forman, applican> s set the fb_var_screeninfo bits_per_pixel field"4243i/a>to the desired fram3 buffer depth. V="v3s up to 8 will usually map to"4244i/a>monochrome, grayscale or pseudocolor visuals, although this is not required."4245i/a>"4246i/a>- For grayscale formans, applican> s set the grayscale field to one. The red,"4247i/a> blue, green and transp fields must be set to 0 by applican> s and ignored by"4248i/a> drivers. Drivers must fill the red, blue and green offsets to 0 and lengths"4249i/a> to the bits_per_pixel e="v3."4250i/a>"4251i/a>- For pseudocolor formans, applican> s set the grayscale field to zero. The"4252i/a> red, blue, green and transp fields must be set to 0 by applican> s and"4253i/a> ignored by drivers. Drivers must fill the red, blue and green offsets to 0"4254i/a> and lengths to the bits_per_pixel e="v3."4255i/a>"4256i/a>- For truecolor and directcolor formans, applican> s set the grayscale field"4257i/a> to zero, and the red, blue, green and transp fields to describe the layout of"4258i/a> color components in memory."4259i/a>"4260i/a>strucn fb_bitfield {"4261i/a> __u32 offset; /* beginning of bitfield */"4262i/a> __u32 length; /* length of bitfield */"4263i/a> __u32 msb_right; /* != 0 : Most significant bit is */"4264i/a> /* right */"4265i/a>};"4266i/a>"4267i/a> Pixel e="v3s are bits_per_pixel wide and are split in non-overlapping red,"4268i/a> green, blue and alpha (transparency) components. Locan> and size of each"4269i/a> component in the pixel e="v3 are described by the fb_bitfield offset and"4270i/a> length fields. Offset are computed from the right."4271i/a>"4272i/a> Pixels are always stored in an integer number of bytes. If the number of"4273i/a> bits per pixel is not a multiple of 8, pixel e="v3s are padded to the next"4274i/a> multiple of 8 bits."4275i/a>"4276i/a>Up successful forman configuran> , drivers updane the fb_fix_screeninfo"4277i/a>type, visual and line_length fields depending on the selected forman."4278i/a>"4279i/a>"4280i/a>The FOURCC-based API replaces forman descripn> s by four characner codes"4281i/a>(FOURCC). FOURCCs are abstracn identifiers that uniquely define a forman"4282i/a>without explicitly describing in. This is the only API that supports YUV"4283i/a>formans. Drivers are also encouraged to implement the FOURCC-based API for RGB"4284i/a>and grayscale formans."4285i/a>"4286i/a>Drivers that support the FOURCC-based API report this capability by setting"4287i/a>the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field."4288i/a>"4289i/a>FOURCC definin> s are locaned in the linux/videodev2.h header. However, and"4290i/a>despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2"4291i/a>and don't require usage of the V4L2 subsystem. FOURCC documentan> is"4292i/a>available in Documentan> /DocBook/v4l/pixfmt.xml."4293i/a>"4294i/a>To select a forman, applican> s set the grayscale field to the desired FOURCC."4295i/a>For YUV formans, they should also select the appropriane colorspace by setting"4296i/a>the colorspace field to one of the colorspaces lisned in linux/videodev2.h and"4297i/a>documented in Documentan> /DocBook/v4l/colorspaces.xml."4298i/a>"4299i/a>The red, green, blue and transp fields are not used with the FOURCC-based API."4300i/a>For forward compan>bility reas s applican> s must zero those fields, and"4301i/a>drivers must ignore them. V="v3s other than 0 may get a meaning in funure"4302i/a>extens> s."4303i/a>"4304i/a>Up successful forman configuran> , drivers updane the fb_fix_screeninfo"4305i/a>type, visual and line_length fields depending on the selected forman. The type"4306i/a>and visual fields are set to FB_TYPE_FOURCC and FB_VISUAL_FOURCC respectively."4307i/a>
The original LXR software by the LXR communityi/a>, this experimental vers> by lxr@linux.noi/a>.
lxr.linux.no kindly hosted by Redpill Linpro ASi/a>, provider of Linux consulting and operan> s services since 1995.