[haiku-commits] haiku: hrev47709 - docs/develop/opengl
- From: kallisti5@xxxxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Tue, 19 Aug 2014 16:39:36 +0200 (CEST)
hrev47709 adds 2 changesets to branch 'master'
old head: f66aa8595c256a17177056f1596901be6b2f7b03
new head: ea28139d8429cbad6103a5fb95beb2d8540cc7b3
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=ea28139+%5Ef66aa85
----------------------------------------------------------------------------
4662c8c: docs: opengl. Add some great documentation provided by Roudolf.
* Posted to the haiku-appserver ML, circa 2005.
* Covers a lot of intended uses of Be's accelerant API's in
depth and compares them to moden cards
ea28139: docs: Update opengl readme info
[ Alexander von Gluck IV <kallisti5@xxxxxxxxxxx> ]
----------------------------------------------------------------------------
2 files changed, 160 insertions(+), 78 deletions(-)
docs/develop/opengl/accelerant-interfaces | 136 ++++++++++++++++++++++++++
docs/develop/opengl/readme | 102 +++++--------------
############################################################################
Commit: 4662c8c0a9668798b2eedcd2041108ccd6630ac9
URL: http://cgit.haiku-os.org/haiku/commit/?id=4662c8c
Author: Alexander von Gluck IV <kallisti5@xxxxxxxxxxx>
Date: Tue Aug 19 14:28:53 2014 UTC
docs: opengl. Add some great documentation provided by Roudolf.
* Posted to the haiku-appserver ML, circa 2005.
* Covers a lot of intended uses of Be's accelerant API's in
depth and compares them to moden cards
----------------------------------------------------------------------------
diff --git a/docs/develop/opengl/accelerant-interfaces
b/docs/develop/opengl/accelerant-interfaces
new file mode 100644
index 0000000..1138b86
--- /dev/null
+++ b/docs/develop/opengl/accelerant-interfaces
@@ -0,0 +1,136 @@
+Posted by Rudolf Nov 22, 2005 to the haiku-appsever ML:
+//www.freelists.org/post/haiku-appserver/new-drawing-bug-Rudolf-some-stuff-for-you,10
+
+More good info @ //www.freelists.org/archive/haiku-appserver
+
+ Be Docs (file: R4_Graphics_Driver_Docs):
+
+ Engine Synchronization
+
+ B_ACCELERANT_ENGINE_COUNT - No feature specific data required.
+ Return the number of acceleration engines that the device may operate
in parallel.
+ It's not required for all engines to be equally capable (i.e. support
the same
+ acceleration features).
+
+ B_ACQUIRE_ENGINE - No feature specific data required.
+ Request exclusive ownership of an acceleration engine with the
capabilities mask specified.
+ The caller is willing to wait up to max_wait micro(milli?)-seconds. If
the request can't be
+ fullfilled before that time expires, the accelerant should return
B_WOULD_BLOCK immediatly.
+ If non-zero, sync_token points to a synchronization token retrieved
from either
+ release_engine() or get_sync_token() to which the engine should be
synchronized before
+ engine acquisition succeeds. See B_SYNC_TO_TOKEN for more details.
The engine_token for
+ the successfully acquired engine is returned in engine_token **et.
+
+ B_RELEASE_ENGINE - No feature specific data required.
+ Relinquish exclusive ownership of the engine specified by engine_token
et. If
+ sync_token *st is non-zero, return a sync_token which can be utilized
to ensure that the
+ specified engine has completed all acceleration operations issued up
this point in time.
+
+ B_WAIT_ENGINE_IDLE - No feature specific data required.
+ Wait for the graphics device to be completely idle (i.e. no current
running or pending
+ acceleration primitives, DMA transfers, etc.).
+
+ B_GET_SYNC_TOKEN - No feature specific data required.
+ Return a synchronization token for the specified engine. sync_token
*st must point at
+ a sync_token which will be updated with the information required to
ensure that a call to
+ sync_to_token() will be able to ensure that the specified engine has
completed all of the
+ acceleration primitives, DMA transfers, etc. that have been issued up
to this point in time.
+
+ B_SYNC_TO_TOKEN - No feature specific data required.
+ Ensure that the engine specified in sync_token *st has completed the
acceleration
+ primitives, DMA transfers, etc., issued up to the point in time
specified in the sync_token.
+
+
+ Rudolf's notes.
+ info on engine_token:
+
+ uint32 ACCELERANT_ENGINE_COUNT(void)
+ exists because in theory a single card can have multiple independant
acceleration engines.
+ For instance one that can do 2D, and one that can do 3D (or
combinations). See
+ 'engine capabilities' flags in Accelerant.h.
+ (note: never seen multiple engines per card yet though. Was this
meant for some very old
+ hardware with seperate 2D and 3D 'blocks'? Although I guess it's
thinkable that multiple
+ equally capable engines would exist as well..)
+
+ In order to distinquish between multiple engines all acceleration
commands are given along
+ with an engine_token *et, aquired when
+ status_t ACQUIRE_ENGINE(uint32 capabilities, uint32 max_wait,
sync_token *st, engine_token **et)
+ was called.
+ status_t SYNC_TO_TOKEN(sync_token *st)
+ is an exeption: here the engine is ID'd by member: (defined in
Accelerant.h)
+ uint32 engine_id.
+ void WAIT_ENGINE_IDLE(void)
+ is an exeption also because this function returns only when *ALL*
engines are completely
+ idle. Hence no need for distinction.
+
+ Furthermore the absense of the use of engine_token in both
SYNC_TO_TOKEN and WAIT_ENGINE_IDLE
+ would seem to indicate these hooks may be used *without having
acquired the engine*. (?).
+
+
+ info on sync_token:
+
+-- How does the acceleration cmd interface work? There's a circular
buffer that stores cmd's.
+ There's a hardware pointer that points 'at' the command currently
being executed (think
+ of stacks: some architectures point to the first 'free' location, some
to the 'last used'
+ location.)
+ There's also a second pointer which points at the first free location,
i.e. where new cmd's
+ will be stored pending execution. This second pointer is a software
maintained pointer (in
+ the driver).
+
+-- What's a sync_token? A Sync_token in nothing more than a extra pointer
(one per token). This
+ pointer points at the first free location in the cmd buffer at that
point in time the
+ sync_token was 'filled'. In theory it doesn't change during the (rest
of the) life-time of
+ the token, although the driver-implementation could (?) do that anyway
for some internal
+ reason.
+ Driver users (i.e. app_server) are responsible for reserving memory
for a sync_token. They
+ pass a pointer to it to the driver (if they want to use it). The
driver in turns fills it
+ with the needed info. Driver users may never modify the content of the
sync_token(s).
+
+-- When would a user be interested in a sync_token? If multiple
independant (so non-overlapping)
+ 'regions' require multiple updates each alternatingly done by software
and acceleration engine,
+ it might be interesting to use sync_tokens (for instance).
+ It would be possible to issue all engine commands concerning area #1,
ask for a sync token,
+ issue all engine commands concerning area #2, and then do this:
+ - SYNC_TO_TOKEN (so waiting until all engine commands concerning area
#1 are done);
+ - Draw in area #1 using software (while the acc engine is in the
process of updating area #2:
+ (so some 'parallel processing' is done here).
+
+ If no sync token would be used, instead of syncing to token,
wait_engine_idle would be used.
+ This of course would mean that no 'parallel processing' could be
done...
+ Worse yet: if some seperate user is also using the engine (between
RELEASE and AQUIRE engine
+ done by 'user #1' (i.e. app_server), the acc engine might *never*
become fully idle.
+ A nice example here would be 3D acceleration: as long as no
non-accelerated drawing has to be
+ done there, there's no reason the engine would need to be idle at all
for this (apart from
+ processing 'user-input' like joystick controls).
+ You see: an acceleration engine automatically serializes it's cmd
processing so update errors
+ because of out-of-order execution wouldn't happen.
+
+-- Why didn't I implement sync_token stuff in the matrox, nvidia and
neomagic drivers?
+ Lack of 'known specs' yet. You see, even if the pointers in the cmd
buffer are known: that's
+ not enough yet:
+ - The fact that an command is fetched from the buffer does *not* mean
it's
+ execution is completely done.
+ - The implementation via just a pointer is not enough: if you wait too
long, the current
+ free pointer might have cycled around the buffer. This means a simple
compare to that
+ pointer is not conclusive. Much better would be actually inserting
'dummy commands' inside
+ the command buffer at the place a sync_token is generated. This dummy
commands would be
+ executed just once, when we reached our goal. If the dummy command
clears a variable
+ especially setup for the sync_token in question: we would have a
conclusive result without
+ even the use of an actual pointer in the sync_token. AND: updating the
tokens would have no
+ software overhead, as the acc engine would do it. (via 'pointers only'
some invalidation
+ code has to be executed once the hardware pointer cycles around).
+
+ NOTE PLEASE:
+ This information is based upon my understanding of hardware inner
workings. As this
+ understanding grows and is corrected over time, I might contradict
myself later on if
+ asked again. :-)
+
+
+//actual hooks:
+ uint32 ACCELERANT_ENGINE_COUNT(void);
+ status_t ACQUIRE_ENGINE(uint32 capabilities, uint32 max_wait,
+sync_token *st, engine_token **et);
+ status_t RELEASE_ENGINE(engine_token *et, sync_token *st);
+ status_t GET_SYNC_TOKEN(engine_token *et, sync_token *st);
+ status_t SYNC_TO_TOKEN(sync_token *st);
+ void WAIT_ENGINE_IDLE(void);
############################################################################
Revision: hrev47709
Commit: ea28139d8429cbad6103a5fb95beb2d8540cc7b3
URL: http://cgit.haiku-os.org/haiku/commit/?id=ea28139
Author: Alexander von Gluck IV <kallisti5@xxxxxxxxxxx>
Date: Tue Aug 19 14:34:33 2014 UTC
docs: Update opengl readme info
----------------------------------------------------------------------------
diff --git a/docs/develop/opengl/readme b/docs/develop/opengl/readme
index 96dd321..87b00d6 100644
--- a/docs/develop/opengl/readme
+++ b/docs/develop/opengl/readme
@@ -12,23 +12,14 @@ In the traditional BeOS sense, the OpenGL Add-ons are the
vendor provided OpenGL drivers. This actually doesn't
mesh well with the current open source OpenGL stack.
-Our "OpenGL Add-ons" are really wrappers around Mesa
-and Gallium code. We gain greater OS control of OpenGL
-rendering with the drawback of increased work overall.
-The OpenGL Add-ons call private Mesa functions, thus
-we get no compatibility saftey net between Mesa versions.
+Our "OpenGL Add-ons" are really self contained Mesa and
+Gallium renderers. On the old Mesa side of the house,
+swrast is a bunch of wrapper code. On the Gallium side,
+swpipe is a Gallium target.
-Our Gallium connecting Add-ons could actually fit into
-the upstream Mesa / Gallium project, however this would
-cause complications in the build process (linking in
-OpenGL and all of it's libraries into a small number of
-shared libraries is not really what the Mesa project
-designs it's stack for. Several symbol collisions exist
-when trying to link libmesa and libgallium together for
-example)
-
-Mesa drivers are the classical Mesa software rasterizers
-Gallium drivers are the new-school software drivers.
+Mesa drivers are the classical Mesa software rasterizers,
+Gallium drivers are the new-school software and hardware
+drivers.
**********
@@ -36,14 +27,14 @@ Mesa versions
The Haiku project uses two different versions of Mesa.
- * Mesa 7.8.2 for gcc2 OpenGL Add-ons
- * Mesa 9.0.1+ for gcc4 OpenGL Add-ons.
+ * Mesa 7.9.2 for gcc2 OpenGL Add-ons
+ * Mesa 10.2.0+ for gcc4 OpenGL Add-ons.
The reasoning behind this is that any version of Mesa
-above 7.8.2 will require a *massive* porting effort to
+above 7.9.2 will require a *massive* porting effort to
make it compile under gcc2. Given this fact, it makes
sense to bump the gcc2 version of Mesa as far as it will
-go and set it there statically. Think of Mesa 7.8.2
+go and set it there statically. Think of Mesa 7.9.2
as the "stable" version Haiku R1 will use :)
Hardware 3D rendering and llvm-based software rendering
@@ -53,68 +44,23 @@ However! If you're running a gcc2 hybrid version of
Haiku, llvm or hardware based rendering should be possible
on gcc4 applications.
-It is *essential* to upgrade our build Mesa packages
-with the latest release Mesa versions. If we fall too
-far behind the update gets extremely tricky as functions
-inside Mesa and Gallium change at a fast pace.
-
-
-**********
-gcc2 OpenGL kit
-
-The following process occurs in order to generate the
-gcc2 (Mesa 7.8.2) OpenGL kit:
-
-* Some kind soul compiles a Mesa optional package on a
- gcc2 Haiku system with the bep on haikuports. This
- gets uploaded to Haiku-files and the package name
- / version gets updated as in the BuildFeatures jam
- build script.
-
- - The bep generally applies a few minimal patches to
- Mesa 7.8.2 and compiles it. Then it rounds up all of
- the headers and static libraries and throws them into
- a .zip for the build
+It's essential someone from the Haiku project keeps up
+with the upstream Mesa changes pushing build fixes to
+upstream Mesa to keep Haiku relevant.
-* Someone starts a gcc2 Haiku build. The build process pulls
- down the Mesa optional package above and links the needed
- parts into libGL and the swrast_legacy OpenGL add-on
**********
-gcc4 OpenGL kit
-
-The following process occurs in order to generate the
-gcc4 (Mesa 9.0.1+) OpenGL kit:
-
-* Some kind soul compiles a Mesa optional package on a
- gcc4 Haiku system with the bep on haikuports. This
- gets uploaded to Haiku-files and the package name
- / version gets updated as in the BuildFeatures jam
- build script.
-
- - The kind soul also needs to install the LLVM Optional
- build package on his build machine *before* compiling
- the Mesa bep. (unless he or she doesn't want llvmpipe
- rendering)
-
- - The bep for Mesa 9.0.1+ doesn't apply too many patches as
- Haiku build fixes are accepted upstream.
-
- - The bep rounds up all of the headers and static
- libraries and throws them into a .zip for the build
-
-* Someone starts a gcc4 Haiku build. The build process pulls
- down the Mesa optional package above and links the needed
- parts into libGL and OpenGL add-ons.
+The packages
- - If the user didn't link in LLVM, he can disable the LLVM
- dependencies in the OpenGL kit Jamfile. swpipe will
- automagically fall back to softpipe rendering
+Haiku has several packages for Mesa:
- - The build system will download the LLVM optional package
- and link it into any OpenGL add-ons that need it.
+mesa-x.x.x-x-x86.hpkg Core Mesa package, provides libGL
+mesa_devel-x.x.x-x-x86.hpkg Provides development headers and "OpenGL kit"
+mesa_swrast-x.x.x-x-x86.hpkg Mesa "Software Rasterization" renderer
+mesa_swpipe-x.x.x-x-x86.hpkg Gallium "Software pipe" LLVM enhanced renderer
- !! The LLVM optional package needs to match the LLVM
- binaries on the machine which compiled Mesa
- !!
+Future :3
+mesa_radeonhd-x.x.x-x-x86.hpkg Gallium "Radeon HD" hardware renderer
+mesa_intel-x.x.x-x-x86.hpkg Gallium "Intel" hardware renderer
+mesa_nvidia-x.x.x-x-x86.hpkg Gallium "nVidia" hardware renderer (unlikely)
Other related posts:
- » [haiku-commits] haiku: hrev47709 - docs/develop/opengl - kallisti5
