diff --git a/archive/libretro-gl.tex b/archive/libretro-gl.tex new file mode 100644 index 00000000..021a2ebd --- /dev/null +++ b/archive/libretro-gl.tex @@ -0,0 +1,80 @@ +\documentclass[11pt]{article} + +\author{Hans-Kristian Arntzen} +\title{Implementing a Hardware Accelerated Libretro Core} + +\begin{document} +\maketitle + +\begin{abstract} +Libretro API~\footnote{http://libretro.org} recently received support for cores to use OpenGL (GL2+ or GLES2) directly instead of software rendering to a buffer which is subsequently used by the frontend. This article explains how a core can take advantage of this, and which considerations must be taken into account. This article assumes familiarity with the libretro API. + +Cores which use hardware rendering can still use known frontend features, such as multi-pass shaders. +This is accomplished by letting cores render to frame buffer objects (FBOs) instead of the back buffer~\footnote{GL drivers must support render-to-texture extensions for this to work.}. + +This addition to the libretro API is designed to be used with hardware-accelerated emulator cores, as well as serving as a framework for graphical demos and experiments. +\end{abstract} + +\section*{Application model} +Using OpenGL in a libretro context is somewhat different than when you use libraries like SDL, GLFW or SFML. In libretro, the frontend owns the OpenGL context. For an application using conventional libraries like SDL, the application will do this: + +\begin{itemize} +\item Initialize, create a window of specific size +\item Initialize OpenGL resources +\item Per frame, handle window events (resize), handle input, render as desired, swap buffers +\item Tear down context and window +\end{itemize} + +Using libretro API, platform specifics like managing windows, rendering surfaces and input are all handled by the frontend. The core will only deal with rendering to a surface. The core renders to an FBO of fixed size, determined by the core. The frontend takes this rendered data and stretches to screen as desired by the user. It can apply shaders, change aspect ratio, etc. This model is equivalent to software rendering where \texttt{retro\_video\_refresh\_t} callback is called. + +\section*{Using OpenGL in libretro} + +\begin{itemize} +\item Use \texttt{RETRO\_ENVIRONMENT\_SET\_PIXEL\_FORMAT} and request a 32-bit format. This is the format that the resulting framebuffer will have~\footnote{In reality, RetroArch converts all 16-bit data (\texttt{RETRO\_PIXEL\_FORMAT\_RGB565}) to 32-bit (\texttt{XRGB8888}) when running desktop GL for performance reasons. In GLES mode, this is not done, however. Do not rely on this behavior, and be explicit about it.}. + +\item Use \texttt{RETRO\_ENVIRONMENT\_SET\_HW\_RENDER} environment callback in \\\texttt{retro\_load\_game()}, notifying frontend that core is using hardware rendering. An OpenGL 2+ or GLES2 context can be specified here. If this is not supported the callback will return false, and you can fallback to software rendering or refuse to start. + +\item In \texttt{retro\_get\_system\_av\_info()}, as normal, \texttt{max\_width} and \\\texttt{max\_height} fields specify the maximum resolution the core will render to. + +\item When the frontend has created a context or reset the context, \\\texttt{retro\_hw\_context\_reset\_t} is called. Here, OpenGL resources can be initialized. +The frontend can reset the context at will (e.g. when changing from fullscreen to windowed mode and vice versa). The core should take this into account. It will be notified when reinitialization needs to happen. + +\item A callback to grab OpenGL symbols is exposed via \\\texttt{retro\_hw\_get\_proc\_address\_t}. Use this to retrieve symbols and extensions. + +\item In \texttt{retro\_run()}, use \texttt{retro\_hw\_get\_current\_framebuffer\_t} callback +to get which FBO to render to~\footnote{e.g. \texttt{glBindFramebuffer(GL\_FRAMEBUFFER, get\_current\_framebuffer())}}. This is your "backbuffer". Do not attempt to render to the real back buffer. You must call this every frame as it can change every frame. The dimensions of this FBO are at least as big as declared in \texttt{max\_width} and \texttt{max\_height}. If desired, the FBO also has a depth buffer attached~\footnote{see \texttt{RETRO\_ENVIRONMENT\_SET\_HW\_RENDER}}. + +\item When done rendering, call \texttt{retro\_video\_refresh\_t} with the macro \texttt{RETRO\_HW\_FRAME\_BUFFER\_VALID} as argument for buffer. Width and height should be specified as well, but pitch argument is irrelevant and will be ignored. If the frame is duped~\footnote{RETRO\_ENVIRONMENT\_CAN\_DUPE}, the buffer argument takes \texttt{NULL} as normal. +\end{itemize} + +\section*{Important considerations in the OpenGL code} +The frontend and libretro core share OpenGL context state. Some considerations have to be taken into account for this cooperation to work nicely. + +\begin{itemize} +\item Don't leave buffers and global objects bound when calling \\\texttt{retro\_video\_refresh\_t}. +Make sure to unbind everything, i.e. VAOs, VBOs, shader programs, textures, etc. Failing to do this could potentially hit strange bugs. The frontend will also follow this rule to avoid clashes. Being tidy here is considered good practice anyway. + +\item The GL viewport will be modified by frontend as well as libretro core. Set this every frame. + +\item \texttt{glEnable()} state like depth testing, etc, is likely to be disabled in frontend as it's just rendering a quad to screen. Enable this per-frame if you use depth testing. +There is no need to disable this before calling \\\texttt{retro\_video\_refresh\_t}. + +\item Avoid VAOs. They tend to break on less-than-stellar drivers~\footnote{At least AMD drivers on Windows are known to break here.}. + +\item Try to write code which is GLES2 as well as GL2+ (w/ extensions) compliant. This ensures maximum target surface for the libretro core. + +\item Libretro treats top-left as origin. OpenGL treats bottom-left as origin. To be compatible with the libretro model, top-left semantics are preserved. Rendering normally will cause the image to be flipped vertically. To avoid this, simply scale the final projection matrix by $[1, -1, 1, 1]$. +\end{itemize} + +\section*{Test implementations} +A very basic test implementation of libretro GL interface is available in RetroArch repository on GitHub~\footnote{https://github.com/Themaister/RetroArch/tree/master/libretro-test-gl}. +It displays two spinning quads. It runs both as a GLES2 and GL2 core depending on \texttt{GLES} environment variable. + +A slightly more involved test core is found on Bitbucket~\footnote{https://bitbucket.org/Themaister/libretro-gl}. It uses instanced rendering of a textured cube, with FPS-style fly-by camera. It uses libretro's mouse API as well. It is valid GLES and GL2 at the same time. + +\section*{Building a libretro core} +Libretro is an interface, and not a utility library. Libretro cores are built as standalone dynamic or static libraries, and as they use GL symbols here, they must link against GL symbols themselves. + +An example of how this can be done is shown in the test implementation~\footnote{https://github.com/Themaister/RetroArch/blob/master/libretro-test-gl/Makefile}. + +\end{document} \ No newline at end of file diff --git a/archive/libretro-shader.lyx b/archive/libretro-shader.lyx new file mode 100644 index 00000000..1ef65874 --- /dev/null +++ b/archive/libretro-shader.lyx @@ -0,0 +1,2192 @@ +#LyX 2.0 created this file. For more info see http://www.lyx.org/ +\lyxformat 413 +\begin_document +\begin_header +\textclass article +\use_default_options true +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding auto +\fontencoding global +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 + +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\spacing single +\use_hyperref true +\pdf_title "Cg/HLSL Libretro shader tutorial" +\pdf_author "Hans-Kristian Antzen, Daniel De Matteis" +\pdf_bookmarks true +\pdf_bookmarksnumbered false +\pdf_bookmarksopen false +\pdf_bookmarksopenlevel 1 +\pdf_breaklinks false +\pdf_pdfborder false +\pdf_colorlinks true +\pdf_backref false +\pdf_pdfusetitle true +\papersize default +\use_geometry false +\use_amsmath 1 +\use_esint 1 +\use_mhchem 1 +\use_mathdots 1 +\cite_engine basic +\use_bibtopic false +\use_indices false +\paperorientation portrait +\suppress_date false +\use_refstyle 1 +\index Index +\shortcut idx +\color #008000 +\end_index +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\paragraph_indentation default +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Title +Cg/HLSL libretro shader tutorial +\end_layout + +\begin_layout Author +Hans-Kristian Arntzen, Daniel De Matteis +\end_layout + +\begin_layout Standard +\begin_inset CommandInset toc +LatexCommand tableofcontents + +\end_inset + + +\end_layout + +\begin_layout Section +Introduction +\end_layout + +\begin_layout Standard +This document is for a (fresh) shader developer that wants to develop shader + programs for use in various emulators/games. + Shader programs run on your GPU, and thus enables very sophisticated effects + to be performed on the picture which might not be possible in real-time + on the CPU. + Some introduction to shader programming in general is given, so more experience +d developers that only need reference for the specification may just skip + ahead. +\end_layout + +\begin_layout Standard +Current emulators that support the specification explained here to a certain + degree are: +\end_layout + +\begin_layout Itemize +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch +\end_layout + +\begin_layout Itemize +\begin_inset Index idx +status open + +\begin_layout Plain Layout +SNES9x +\end_layout + +\end_inset + +SNES9x Win32 +\end_layout + +\begin_layout Standard +There are three popular shader languages in use today: +\end_layout + +\begin_layout Itemize +\begin_inset Index idx +status open + +\begin_layout Plain Layout +HLSL +\end_layout + +\end_inset + +HLSL (High-Level Shading Language, Direct3D) +\end_layout + +\begin_layout Itemize +\begin_inset Index idx +status open + +\begin_layout Plain Layout +GLSL +\end_layout + +\end_inset + +GLSL (GL Shading Language, OpenGL) +\end_layout + +\begin_layout Itemize +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Cg +\end_layout + +\end_inset + +Cg (HLSL/GLSL, nVidia) +\end_layout + +\begin_layout Standard +The spec is for the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Cg +\end_layout + +\end_inset + +Cg shading language developed by nVidia. + It +\begin_inset Quotes eld +\end_inset + +wraps +\begin_inset Quotes erd +\end_inset + + around +\begin_inset Index idx +status open + +\begin_layout Plain Layout +OpenGL +\end_layout + +\end_inset + +OpenGL and +\begin_inset Index idx +status open + +\begin_layout Plain Layout +HLSL +\end_layout + +\end_inset + +HLSL to make shaders written in Cg quite portable. + It is also the shading language implemented on the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +PlayStation3 +\end_layout + +\end_inset + +PlayStation3, thus increasing the popularity of it. +\end_layout + +\begin_layout Subsection +The rendering pipeline +\end_layout + +\begin_layout Standard +With shaders you are able to take control over a large chunk of the GPUs + inner workings by writing your own programs that are uploaded and run on + the GPU. + In the old days, GPUs were a big black box that was highly configurable + using endless amount of API calls. + In more modern times, rather than giving you endless amounts of buttons, + you are expected to implement the few «buttons» you actually need, and + have a streamlined API. +\end_layout + +\begin_layout Standard +The rendering pipeline is somewhat complex, but we can in general simplify + it to: +\end_layout + +\begin_layout Itemize +Vertex processing +\end_layout + +\begin_layout Itemize +Rasterization +\end_layout + +\begin_layout Itemize +Fragment processing +\end_layout + +\begin_layout Itemize +Framebuffer blend +\end_layout + +\begin_layout Standard +We are allowed to take control of what happens during vertex processing, + and fragment processing. +\end_layout + +\begin_layout Subsection +A Cg/HLSL program +\end_layout + +\begin_layout Standard +If you were to process an image on a CPU, you would most likely do something + like this: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +for (unsigned y = 0; y < height; y++) { +\end_layout + +\begin_layout Plain Layout + + for (unsigned x = 0; x < width; x++) +\end_layout + +\begin_layout Plain Layout + + out_pixel[y][x] = process_pixel(in_pixel[y][x], y, x); +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + We quickly realize that this is highly serial and slow. + We see that out_pixel[y][x] isn't dependent on out_pixel[y + k][x + k], + so we see that we can parallelize quite a bit. +\end_layout + +\begin_layout Standard +Essentially, we only need to implement process_pixel() as a single function, + which is called thousands, even millions of time every frame. + The only purpose in life for process_pixel() is to process an input, and + produce an output. + No state is needed, thus, a +\begin_inset Quotes eld +\end_inset + +pure +\begin_inset Quotes erd +\end_inset + + function in computer science terms. +\end_layout + +\begin_layout Standard +For the Cg program, we need to implement two different functions. +\end_layout + +\begin_layout Standard +main_vertex() takes care of transforming every incoming vertex from camera + space down to clip space. + This essentially means projection of 3D (coordinates on GPU) down to 2D + (your screen) +\begin_inset Foot +status collapsed + +\begin_layout Plain Layout +Since we're dealing with old school emulators here, which are already 2D, + the vertex shading is very trivial. +\end_layout + +\end_inset + +. + +\end_layout + +\begin_layout Standard +Vertex shaders get various coordinates as input, and uniforms. + Every vertex emitted by the emulator is run through main_vertex which calculate +s the final output position +\begin_inset Foot +status collapsed + +\begin_layout Plain Layout +For our emulators this is just 4 times, since we're rendering a quad on + the screen. + 3D games would obviously have a lot more vertices. +\end_layout + +\end_inset + +. + +\end_layout + +\begin_layout Standard +While coordinates differ for each invocation, uniforms are constant throughout + every call. + Think of it as a global variable that you're not allowed to change. +\end_layout + +\begin_layout Standard +Vertex shading can almost be ignored altogether, but since the vertex shader + is run only 4 times, and the fragment shader is run millions of times per + frame, it is a good idea to precalculate values in vertex shader that can + later be used in fragment shader. + There are some limitiations to this which will be mentioned later. +\end_layout + +\begin_layout Standard +main_fragment() takes care of calculating a pixel color for every single + output pixel on the screen. + If you're playing at 1080p, the fragment shader will have to be run 1920 + * 1080 times! This is obviously straining on the GPU unless the shader + is written efficiently. +\end_layout + +\begin_layout Standard +Obviously, main_fragment is where the real action happens. + For many shaders we can stick with a +\begin_inset Quotes eld +\end_inset + +dummy +\begin_inset Quotes erd +\end_inset + + vertex shader which does some very simple stuff. +\end_layout + +\begin_layout Standard +The fragment shader receives a handle to a texture (the game frame itself), + and the texture coordinate for the current pixel, and a bunch of uniforms. +\end_layout + +\begin_layout Standard +A fragment shader's final output is a color, simple as that. + Processing ends here. +\end_layout + +\begin_layout Section +Hello World +\end_layout + +\begin_layout Standard +We'll start off with the basic vertex shader. + No fancy things are being done. + You'll see a similiar vertex shader in most of the Cg programs out there + in the wild. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +void main_vertex( +\end_layout + +\begin_layout Plain Layout + + float4 pos : POSITION, +\end_layout + +\begin_layout Plain Layout + + out float4 out_pos : POSITION, +\end_layout + +\begin_layout Plain Layout + + uniform float4x4 modelViewProj, +\end_layout + +\begin_layout Plain Layout + + float4 color : COLOR, +\end_layout + +\begin_layout Plain Layout + + out float4 out_color : COLOR, +\end_layout + +\begin_layout Plain Layout + + float2 tex : TEXCOORD, +\end_layout + +\begin_layout Plain Layout + + out float2 out_tex : TEXCOORD +\end_layout + +\begin_layout Plain Layout + +) +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + out_pos = mul(modelViewProj, pos); +\end_layout + +\begin_layout Plain Layout + + out_color = color; +\end_layout + +\begin_layout Plain Layout + + out_tex = tex; +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +This looks vaguely familiar to C, and it is. + +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Cg +\end_layout + +\end_inset + +Cg stands for +\begin_inset Quotes eld +\end_inset + +C for graphics +\begin_inset Quotes erd +\end_inset + + after all. + We notice some things are happening, notable some new types. +\end_layout + +\begin_layout Subsection +Cg types +\end_layout + +\begin_layout Subsubsection +Float4 +\end_layout + +\begin_layout Standard +float4 is a vector type. + It contains 4 elements. + It could be colors, positions, whatever. + It's used for vector processing which the GPUs are extremely efficient + at. +\end_layout + +\begin_layout Subsubsection +Semantics +\end_layout + +\begin_layout Standard +We see various semantics. + The POSITION semantic means that the variable is tied to vertex coordinates. + We see that we have an input POSITION, and an output (out) POSITION. + We thus transform the input to the output with a matrix multiply with the + current model-view projection. + Since this matrix is the same for every vertex, it is a uniform. + Remember that the variable names DO matter. + modelViewProj has to be called exactly that, as the emulator will pass + the MVP to this uniform. + It is in the specification. +\end_layout + +\begin_layout Standard +Since we have semantics for the POSITION, etc, we can call them whatever + we want, as the Cg environment figures out what the variables mean. +\end_layout + +\begin_layout Standard +The transformation happens here: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +out_pos = mul(modelViewProj, pos); +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +The COLOR semantic isn't very interesting for us, but the example code in + nVidias Cg documentation includes it, so we just follow along. +\end_layout + +\begin_layout Standard +TEXCOORD is the texture coordinate we get from the emulator, and generally + we just pass it to the fragment shader directly. + The coordinate will then be +\begin_inset Quotes eld +\end_inset + +linearly interpolated +\begin_inset Quotes erd +\end_inset + + across the fragments. + More complex shaders can output (almost) as many variables they want, that + will be linearily interpolated for free to the fragment shader. +\end_layout + +\begin_layout Standard +We also need a fragment shader to go along with the vertex shader, and here's + a basic shader that only outputs the pixel as-is. + This is pretty much the result you'd get if you didn't run any shader (fixed-fu +nction) at all. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, +\end_layout + +\begin_layout Plain Layout + + float2 tex : TEXCOORD) : COLOR +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + return tex2D(s0, tex); +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +This is arguably simpler than the vertex shader. + Important to notice are: +\end_layout + +\begin_layout Standard +sampler2D is a handle to a texture in Cg. + The semantic here is TEXUNIT0, which means that it refers to the texture + in texture unit 0. + This is also part of the specification. +\end_layout + +\begin_layout Standard +float2 tex : TEXCOORD is the interpolated coordinate we received from the + vertex shader. +\end_layout + +\begin_layout Standard +tex2D(s0, tex); simply does texture lookup and returns a COLOR, which is + emitted to the framebuffer. + Simple enough. + Practically every fragment does more than one texture lookup. + For example, classic pixel shaders look at the neighbor pixels as well + to determine the output. + But where is the neighbor pixel? We'll revise the fragment shader and try + to make a really blurry shader to demonstrate. + We now need to pull up some uniforms. + We need to know how to modify our tex coordinates so that it points to + a neighbor pixel. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +struct input +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float2 video_size; +\end_layout + +\begin_layout Plain Layout + + float2 texture_size; +\end_layout + +\begin_layout Plain Layout + + float2 output_size; +\end_layout + +\begin_layout Plain Layout + + float frame_count; +\end_layout + +\begin_layout Plain Layout + +}; +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, +\end_layout + +\begin_layout Plain Layout + + uniform input IN, float2 tex : TEXCOORD) : COLOR +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float4 result = float4(0.0); +\end_layout + +\begin_layout Plain Layout + + float dx = 1.0 / IN.texture_size.x; +\end_layout + +\begin_layout Plain Layout + + float dy = 1.0 / IN.texture_size.y; +\end_layout + +\begin_layout Plain Layout + + +\end_layout + +\begin_layout Plain Layout + + // Grab some of the neighboring pixels and +\end_layout + +\begin_layout Plain Layout + + // blend together for a very mushy blur. +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(-dx, -dy)); +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(dx, -dy)); +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(0.0, 0.0)); +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(-dx, 0.0)); +\end_layout + +\begin_layout Plain Layout + + return result / 4.0; +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Here we use IN.texture_size to determine the the size of the texture. + Since GL maps the whole texture to the interval [0.0, 1.0], 1.0 / IN.texture_size + means we get the offset for a single pixel, simple enough. + Almost every shader uses this. + We can calculate these offsets in vertex shader to improve performance + since the coordinates are linearily interpolated anyways, but that is for + another time ... + ;) +\end_layout + +\begin_layout Subsection +Putting it together +\end_layout + +\begin_layout Standard +The final runnable product is a single .cg file with the main_vertex and + main_fragment functions added together. + Not very complicated. + For the icing on the cake, you should add a license header. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +/* Stupid blur shader. +\end_layout + +\begin_layout Plain Layout + + Author: Your friendly neighbor. +\end_layout + +\begin_layout Plain Layout + + License: We don't have those things! +\end_layout + +\begin_layout Plain Layout + +*/ +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +struct input +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float2 video_size; +\end_layout + +\begin_layout Plain Layout + + float2 texture_size; +\end_layout + +\begin_layout Plain Layout + + float2 output_size; +\end_layout + +\begin_layout Plain Layout + + float frame_count; +\end_layout + +\begin_layout Plain Layout + +}; +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +void main_vertex( +\end_layout + +\begin_layout Plain Layout + + float4 pos : POSITION, +\end_layout + +\begin_layout Plain Layout + + out float4 out_pos : POSITION, +\end_layout + +\begin_layout Plain Layout + + uniform float4x4 modelViewProj, +\end_layout + +\begin_layout Plain Layout + + float4 color : COLOR, +\end_layout + +\begin_layout Plain Layout + + out float4 out_color : COLOR, +\end_layout + +\begin_layout Plain Layout + + float2 tex : TEXCOORD, +\end_layout + +\begin_layout Plain Layout + + out float2 out_tex : TEXCOORD +\end_layout + +\begin_layout Plain Layout + +) +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + out_pos = mul(modelViewProj, pos); +\end_layout + +\begin_layout Plain Layout + + out_color = color; out_tex = tex; +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, +\end_layout + +\begin_layout Plain Layout + + uniform input IN, float2 tex : TEXCOORD) : COLOR +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float4 result = float4(0.0); +\end_layout + +\begin_layout Plain Layout + + float dx = 1.0 / IN.texture_size.x; +\end_layout + +\begin_layout Plain Layout + + float dy = 1.0 / IN.texture_size.y; +\end_layout + +\begin_layout Plain Layout + + +\end_layout + +\begin_layout Plain Layout + + // Grab some of the neighboring pixels and blend +\end_layout + +\begin_layout Plain Layout + + // together for a very mushy blur. +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(-dx, -dy)); +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(dx, -dy)); +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(0.0, 0.0)); +\end_layout + +\begin_layout Plain Layout + + result += tex2D(s0, tex + float2(-dx, 0.0)); +\end_layout + +\begin_layout Plain Layout + + return result / 4.0; +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Result +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename supermetroid.jpg + lyxscale 50 + scale 30 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{The result of the shader code.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +As you can see, it's not a practical shader, but it shows the blurring effect + to the extreme. +\end_layout + +\begin_layout Section +Expanding further +\end_layout + +\begin_layout Subsection +Lookup textures +\end_layout + +\begin_layout Standard +We'll first mention a very popular feature among RetroArch users the ability + to access external textures. + This means we have several samplers available for use. + In the config file, we define the textures as so: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +textures = "foo;bar" +\end_layout + +\begin_layout Plain Layout + +foo = path_foo.png +\end_layout + +\begin_layout Plain Layout + +bar = bar_foo.png +\end_layout + +\begin_layout Plain Layout + +foo_linear = true # Linear filtering for foo. +\end_layout + +\begin_layout Plain Layout + +bar_linear = true # Linear filtering for bar. + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +RetroArch PS3 uses PNG as the main format, RetroArch can use whatever if + Imlib2 support is compiled in. + If not, it's restricted to lop-left ordered, non-RLE TGA. +\end_layout + +\begin_layout Standard +From here on, +\begin_inset Quotes eld +\end_inset + +foo +\begin_inset Quotes erd +\end_inset + + and +\begin_inset Quotes eld +\end_inset + +bar +\begin_inset Quotes erd +\end_inset + + can be found as uniforms in the shaders. + The texture coordinates for the lookup texture will be found in TEXCOORD1. + This can simply be passed along with TEXCOORD0 in the vertex shader as + we did with TEXCOORD0. + Here we make a fragment shader that blends in two background picture at + a reduced opacity. + Do NOT assign lookup textures to a certain TEXUNIT, Cg will assign a fitting + texture unit to the sampler. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +float4 main_fragment(uniform sampler2D s0 : TEXUNIT0, +\end_layout + +\begin_layout Plain Layout + + uniform sampler2D foo, uniform sampler2D bar, +\end_layout + +\begin_layout Plain Layout + + float2 tex : TEXCOORD0, float2 tex_lut : TEXCOORD1) : COLOR +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float4 bg_sum = (tex2D(foo, tex_lut) + tex2D(bar, tex_lut)) * 0.15; +\end_layout + +\begin_layout Plain Layout + + return lerp(tex2D(s0, tex), bg_sum, bg_sum.a); // Alpha blending. +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + Here's an example of what can be achieved using borders (which are just + a simple lookup texture): +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename shader-rarch-2.jpg + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{A shader making use of a lookup texture for the purpose of drawing + a background border.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Multipass +\end_layout + +\begin_layout Standard +It is sometimes feasible to process an effect in several steps. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +shaders = 2 +\end_layout + +\begin_layout Plain Layout + +shader0 = pass1.cg +\end_layout + +\begin_layout Plain Layout + +shader1 = pass2.cg +\end_layout + +\begin_layout Plain Layout + +scale_type0 = source +\end_layout + +\begin_layout Plain Layout + +scale0 = 2.0 +\end_layout + +\begin_layout Plain Layout + +filter_linear0 = true +\end_layout + +\begin_layout Plain Layout + +filter_linear1 = false +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Game-aware shaders +\end_layout + +\begin_layout Standard +This is a new and exciting feature. + It allows shaders to grab data from the emulator state itself, such as + RAM data. + This is only implemented for SNES so far, but the idea is quite extendable + and portable. +\end_layout + +\begin_layout Standard +The basic idea is that we capture RAM data in a certain way (semantic if + you will) from the SNES, and pass it as a uniform to the shader. + The shader can thus act on game state in interesting ways. +\end_layout + +\begin_layout Standard +As a tool to show this feature, we'll focus on replicating the simple tech + demo shown on YouTube: +\begin_inset CommandInset href +LatexCommand href +target "http://www.youtube.com/watch?v=4VzaE9q735k" + +\end_inset + + +\end_layout + +\begin_layout Standard +What happens is that when Mario jumps in the water, the screen gets a +\begin_inset Quotes eld +\end_inset + +watery +\begin_inset Quotes erd +\end_inset + + effect applied to it, with a rain lookup texture, and a wavy effect. + When he jumps out of the water, the water effect slowly fades away. +\end_layout + +\begin_layout Standard +We thus need to know two things: +\end_layout + +\begin_layout Itemize +Is Mario currently in water or not? +\end_layout + +\begin_layout Itemize +If not, how long time was it since he jumped out? +\end_layout + +\begin_layout Standard +Since shaders do not have state associated with it, we have to let the environme +nt provide the state we need in a certain way. + We'll call this concept a semantic. +\end_layout + +\begin_layout Standard +To capture a RAM value directly, we can use the +\begin_inset Quotes eld +\end_inset + +capture +\begin_inset Quotes erd +\end_inset + + semantic. + To record the time when the RAM value last changed, we can use the +\begin_inset Quotes eld +\end_inset + +transition +\begin_inset Quotes erd +\end_inset + + semantic. + We obviously also need to know where in RAM we can find this information. + Luckily, the guys over at SMW Central know the answer: +\begin_inset CommandInset href +LatexCommand href +target "http://www.smwcentral.net/?p=map&type=ram" + +\end_inset + + +\end_layout + +\begin_layout Standard +We see: +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +$7E:0075, byte, Flag, Player is in water flag. + #$00 = No; #$01 = Yes. + +\end_layout + +\end_inset + +Bank $7E and $7F are mapped to WRAM $0000-$FFFF and $10000-$1FFFF respectively. + Thus, our WRAM address is $0075. +\end_layout + +\begin_layout Standard +In the config file, we can now set up the uniforms we'll want to be captured + in the config file. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +imports = "mario_water;mario_water_time" +\end_layout + +\begin_layout Plain Layout + +mario_water_semantic = capture +\end_layout + +\begin_layout Plain Layout + +# Capture the RAM value as-is. +\end_layout + +\begin_layout Plain Layout + +mario_water_wram = 0075 +\end_layout + +\begin_layout Plain Layout + +# This value is hex! +\end_layout + +\begin_layout Plain Layout + +mario_water_time_semantic = transition +\end_layout + +\begin_layout Plain Layout + +# Capture the frame count when this variable last changed. +\end_layout + +\begin_layout Plain Layout + +# Use with IN.frame_count, to create a fade-out effect. +\end_layout + +\begin_layout Plain Layout + +mario_water_time_wram = 0075 +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +The amount of possible +\begin_inset Quotes eld +\end_inset + +semantics +\begin_inset Quotes erd +\end_inset + + are practically endless. + It might be worthwhile to attempt some possibility to run custom code that + keeps track of the shader uniforms in more sophisticated ways later on. + Do note that there is also a %s_mask value which will let you bitmask the + RAM value to check for bit-flags more easily. +\end_layout + +\begin_layout Standard +Now that we got that part down, let's work on the shader design. + In the fragment shader we simply render both the full water effect, and + the «normal» texture, and let a +\begin_inset Quotes eld +\end_inset + +blend +\begin_inset Quotes erd +\end_inset + + variable decide. + We can say that 1.0 is full water effect, 0.0 is no effect. + We can start working on our vertex shader. + We will do something useful here for once. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +struct input +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float frame_count; +\end_layout + +\begin_layout Plain Layout + +}; +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +void main_vertex( +\end_layout + +\begin_layout Plain Layout + + float4 pos : POSITION, +\end_layout + +\begin_layout Plain Layout + + out float4 out_pos : POSITION, +\end_layout + +\begin_layout Plain Layout + + uniform float4x4 modelViewProj, +\end_layout + +\begin_layout Plain Layout + + float4 color : COLOR, +\end_layout + +\begin_layout Plain Layout + + out float4 out_color : COLOR, +\end_layout + +\begin_layout Plain Layout + + float2 tex : TEXCOORD0, +\end_layout + +\begin_layout Plain Layout + + out float2 out_tex : TEXCOORD0, +\end_layout + +\begin_layout Plain Layout + + float2 tex1 : TEXCOORD1, +\end_layout + +\begin_layout Plain Layout + + out float2 out_tex1 : TEXCOORD1, +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + + // Even if the data should have been int, +\end_layout + +\begin_layout Plain Layout + + // Cg doesn't seem to +\end_layout + +\begin_layout Plain Layout + + uniform float mario_water, +\end_layout + +\begin_layout Plain Layout + + // support integer uniforms +\end_layout + +\begin_layout Plain Layout + + uniform float mario_water_time, +\end_layout + +\begin_layout Plain Layout + + uniform input IN, +\end_layout + +\begin_layout Plain Layout + + // Blend factor is passed to fragment shader. +\end_layout + +\begin_layout Plain Layout + + // We'll output the same value in every vertex, +\end_layout + +\begin_layout Plain Layout + + // so every fragment will get the same value +\end_layout + +\begin_layout Plain Layout + + // for blend_factor since there is nothing to interpolate. +\end_layout + +\begin_layout Plain Layout + + out float blend_factor ) +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + out_pos = mul(modelViewProj, pos); +\end_layout + +\begin_layout Plain Layout + + out_color = color; +\end_layout + +\begin_layout Plain Layout + + out_tex = tex; +\end_layout + +\begin_layout Plain Layout + + out_tex1 = tex1; +\end_layout + +\begin_layout Plain Layout + + float transition_time = 0.5 * +\end_layout + +\begin_layout Plain Layout + + (IN.frame_count – mario_water_time) / 60.0; +\end_layout + +\begin_layout Plain Layout + + +\end_layout + +\begin_layout Plain Layout + + // If Mario is in the water ($0075 != 0), +\end_layout + +\begin_layout Plain Layout + + // it's always 1 ... +\end_layout + +\begin_layout Plain Layout + + if (mario_water > 0.0) +\end_layout + +\begin_layout Plain Layout + + blend_factor = 1.0; +\end_layout + +\begin_layout Plain Layout + + // Fade out from 1.0 towards 0.0 as +\end_layout + +\begin_layout Plain Layout + + // transition_time grows larger. +\end_layout + +\begin_layout Plain Layout + + else +\end_layout + +\begin_layout Plain Layout + + blend_factor = exp(-transition_time); +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +All fine and dandy so far, now we just need to use this blend_factor in + our fragment shader somehow ... + Let's move on to the fragment shader where we blend. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +float apply_wave(float2 pos, float2 src, float cnt) +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float2 diff = pos - src; +\end_layout + +\begin_layout Plain Layout + + float dist = 300.0 * sqrt(dot(diff, diff)); +\end_layout + +\begin_layout Plain Layout + + dist -= 0.15 * cnt; +\end_layout + +\begin_layout Plain Layout + + return sin(dist); +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +// Fancy shizz to create a wave. +\end_layout + +\begin_layout Plain Layout + +float4 water_texture(float4 output, float2 scale, float cnt) +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float res = apply_wave(scale, src0, cnt); +\end_layout + +\begin_layout Plain Layout + + res += apply_wave(scale, src1, cnt); +\end_layout + +\begin_layout Plain Layout + + res += apply_wave(scale, src2, cnt); +\end_layout + +\begin_layout Plain Layout + + res += apply_wave(scale, src3, cnt); +\end_layout + +\begin_layout Plain Layout + + res += apply_wave(scale, src4, cnt); +\end_layout + +\begin_layout Plain Layout + + res += apply_wave(scale, src5, cnt); +\end_layout + +\begin_layout Plain Layout + + res += apply_wave(scale, src6, cnt); +\end_layout + +\begin_layout Plain Layout + + return output * (0.95 + 0.012 * res); +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +float4 main_fragment +\end_layout + +\begin_layout Plain Layout + +( +\end_layout + +\begin_layout Plain Layout + + uniform input IN, +\end_layout + +\begin_layout Plain Layout + + float2 tex : TEXCOORD0, uniform sampler2D s0 : TEXUNIT0, +\end_layout + +\begin_layout Plain Layout + + uniform sampler2D rain, float2 tex1 : TEXCOORD1, +\end_layout + +\begin_layout Plain Layout + + in float blend_factor // Passed from vertex +\end_layout + +\begin_layout Plain Layout + +) : COLOR +\end_layout + +\begin_layout Plain Layout + +{ +\end_layout + +\begin_layout Plain Layout + + float4 water_tex = water_texture(tex2D(s0, tex), tex1, IN.frame_count); +\end_layout + +\begin_layout Plain Layout + + float4 normal_tex = tex2D(s0, tex); +\end_layout + +\begin_layout Plain Layout + + float4 rain_tex = tex2D(rain, tex1); +\end_layout + +\begin_layout Plain Layout + + +\end_layout + +\begin_layout Plain Layout + + // First, blend normal and water texture together, +\end_layout + +\begin_layout Plain Layout + + // then add the rain texture with alpha blending on top +\end_layout + +\begin_layout Plain Layout + + return lerp(lerp(normal_tex, water_tex, blend_factor), +\end_layout + +\begin_layout Plain Layout + + rain_tex, rain_tex.a * blend_factor * 0.5); +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +RetroArch config file +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +shaders = 1 +\end_layout + +\begin_layout Plain Layout + +shader0 = mario.cg +\end_layout + +\begin_layout Plain Layout + +filter_linear0 = true +\end_layout + +\begin_layout Plain Layout + +imports = "mario_water;mario_water_time" +\end_layout + +\begin_layout Plain Layout + +mario_water_semantic = capture +\end_layout + +\begin_layout Plain Layout + +mario_water_time_semantic = transition +\end_layout + +\begin_layout Plain Layout + +mario_water_wram = 0075 +\end_layout + +\begin_layout Plain Layout + +mario_water_time_wram = 0075 +\end_layout + +\begin_layout Plain Layout + +textures = rain +\end_layout + +\begin_layout Plain Layout + +rain = rain.tga +\end_layout + +\begin_layout Plain Layout + +rain_linear = true +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +How to test when developing for RetroArch? +\end_layout + +\begin_layout Standard +To develop these kinds of shaders, I'd recommend using +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch w/ +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Cg +\end_layout + +\end_inset + +Cg support, and a debugging tool for your emulator of choice to peek at + RAM values (build it for +\begin_inset Index idx +status open + +\begin_layout Plain Layout +bSNES +\end_layout + +\end_inset + +bSNES yourself with options=debugger). +\end_layout + +\begin_layout Standard +After written, the shader should translate nicely over to RetroArch with + some slight changes to the config. +\end_layout + +\begin_layout Subsubsection +Results +\end_layout + +\begin_layout Standard +Here are some screenshots of the mario effect (in Super Mario World SNES) + we developed. + Obviously this is a very simple example showing what can be done. + It's not confined to overlays. + The imagination is the limit here. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename mario-water1.jpg + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{Super Mario World prior to Mario jumping in water.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename mario-water2.jpg + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{Super Mario World with a game aware shader applying a LUT texture + as soon as Mario jumps into the water.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset CommandInset index_print +LatexCommand printindex +type "idx" + +\end_inset + + +\end_layout + +\end_body +\end_document diff --git a/archive/libretro.lyx b/archive/libretro.lyx new file mode 100644 index 00000000..8fe6b11b --- /dev/null +++ b/archive/libretro.lyx @@ -0,0 +1,1169 @@ +#LyX 2.0 created this file. For more info see http://www.lyx.org/ +\lyxformat 413 +\begin_document +\begin_header +\textclass article +\use_default_options true +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding auto +\fontencoding global +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 + +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\spacing single +\use_hyperref true +\pdf_title "Libretro - Implementing the core" +\pdf_author "Hans-Kristian Arntzen, Daniel De Matteis" +\pdf_bookmarks true +\pdf_bookmarksnumbered false +\pdf_bookmarksopen false +\pdf_bookmarksopenlevel 1 +\pdf_breaklinks false +\pdf_pdfborder true +\pdf_colorlinks true +\pdf_backref false +\pdf_pdfusetitle true +\papersize default +\use_geometry false +\use_amsmath 1 +\use_esint 1 +\use_mhchem 1 +\use_mathdots 1 +\cite_engine basic +\use_bibtopic true +\use_indices false +\paperorientation portrait +\suppress_date false +\use_refstyle 1 +\index Index +\shortcut idx +\color #008000 +\end_index +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\paragraph_indentation default +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Title +Libretro - Implementing the core +\end_layout + +\begin_layout Author +Hans-Kristian Arntzen, Daniel De Matteis +\end_layout + +\begin_layout Standard +\begin_inset CommandInset toc +LatexCommand tableofcontents + +\end_inset + + +\end_layout + +\begin_layout Abstract +This document explains how to successfully implement a library based on + the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro API. + Several reasons for why more emulators and game engines should run in +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro are outlined. +\end_layout + +\begin_layout Section +Background +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch is a project that aims to be a center for “retro” gaming experiences. + For your quick fix of 2D gaming goodness, +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch aims to provide a simple, featureful uniform interface for many + different gaming systems. +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +Libretro is an API that abstracts the inner functionality of a gaming system. + +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch can load a library that implements this API, give it a ROM, and + play. + A key design is that libretro implementations are loaded as libraries. + This ensures great modularity, and flexibility for a developer of a core. +\end_layout + +\begin_layout Standard +Due to its simple and open API, other frontends can just as easily utilize + libretro implementations. +\end_layout + +\begin_layout Standard +While “retro” would often imply an emulator of a classic system, +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro can also abstract a game engine. + Classics such as +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Cave Story +\end_layout + +\end_inset + +Cave Story (NXEngine) and +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Doom +\end_layout + +\end_inset + +DOOM (PrBoom) have already been ported over. +\end_layout + +\begin_layout Section +Portability +\end_layout + +\begin_layout Standard +Most emulator authors write both the backend and frontend to their project. + The question of portability inevitably rises when the frontend is developed. + Should one target a single platform with high level of integration or take + a multi-platform approach with libraries like +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Qt +\end_layout + +\end_inset + +Qt? Backends for essentials like video, audio and input take a lot of time + and effort to get right, especially on multiple platforms. +\end_layout + +\begin_layout Standard +By implementing for +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro, one can target standard C/C++ (or any language that can export + a C API), and achieve instant portability across tons of platforms. +\end_layout + +\begin_layout Standard +In 2012, we would argue that portability has never been more relevant. + There are three major operating systems on the desktop, two major smart + phone platforms, and three gaming consoles. + If your system is implemented with software rendering, your implementation + can run on all systems supported by the frontend, without writing any platform + specific code. + In the case of +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch these are currently: +\end_layout + +\begin_layout Itemize +Windows +\end_layout + +\begin_layout Itemize +Linux +\end_layout + +\begin_layout Itemize +OSX +\end_layout + +\begin_layout Itemize +GameCube +\end_layout + +\begin_layout Itemize +PlayStation 3 +\end_layout + +\begin_layout Itemize +XBox 1 +\end_layout + +\begin_layout Itemize +XBox 360 +\end_layout + +\begin_layout Itemize +Wii +\end_layout + +\begin_layout Itemize +Android +\end_layout + +\begin_layout Section +Features +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch has been in development for about two years. + During this time, some features have shown to be quinessential to retro + gaming systems. + Implementing the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro API correctly, these features can be utilized without any additional + work. +\end_layout + +\begin_layout Subsection +Frame-by-frame rewind +\end_layout + +\begin_layout Standard +A libretro implementation that implements serialization and unserialization + of internal state is able to transparently support rewind mechanics. + While many emulators support coarse grained rewind, +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch supports rewind at the frame level, i.e., frames can be rewound + one frame at a time, similar to the indie-title +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Braid +\end_layout + +\end_inset + +Braid. +\end_layout + +\begin_layout Subsection +\begin_inset Index idx +status open + +\begin_layout Plain Layout +FFmpeg +\end_layout + +\end_inset + +FFmpeg lossless recording +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch can utilize the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libavcodec +\end_layout + +\end_inset + +libavcodec library to encode video and audio output from a libretro implementati +on. + The data is encoded losslessly, with +\begin_inset Index idx +status open + +\begin_layout Plain Layout +FLAC +\end_layout + +\end_inset + +FLAC as audio codec, and cutting-edge +\begin_inset Index idx +status open + +\begin_layout Plain Layout +H.264 +\end_layout + +\end_inset + +H.264/RGB (libx264) encoding, with a fallback to FFV1 for older playback + systems that don't support the modern +\begin_inset Index idx +status open + +\begin_layout Plain Layout +H.264 +\end_layout + +\end_inset + +H.264/RGB variant. + The recorder is multithreaded, and easily performs real-time. +\end_layout + +\begin_layout Subsection +Advanced GPU shader support +\end_layout + +\begin_layout Standard +Classic 2D games have the advantage that their video output is very flexible, + that is, it can be post- processed easily. + Before the advent of programmable GPUs, video filters had to be performed + on the main CPU, which cut directly into performance, and severely limited + the types of filters possible to acheive in real-time. + RetroArch aims to move this processing to the GPU by using shaders. + A vast amount of shader effects are written already, and the shader format + used is documented and implemented independently by other frontends as + well. +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch's shader support is more advanced than most emulators. + It supports an arbitrary amount of shader passes, look-up textures (borders), + scriptable shaders that can react dynamically to input or game content. +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch still supports use of traditional CPU filters, however, it should + be considered a fallback if GPU support is broken. +\end_layout + +\begin_layout Subsection +Peer-to-peer netplay +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch supports two-player action over the network. + It employs a rollback technique that aims to hide latency as much as possible, + similar to the method employed by +\begin_inset Index idx +status open + +\begin_layout Plain Layout +GGPO +\end_layout + +\end_inset + +GGPO. +\end_layout + +\begin_layout Standard +In addition to head-to-head multiplayer, a spectator mode is implemented. + This mode allows a host to live stream playback to several watchers in + real-time. + The bandwidth required for this mode is near- zero as only raw input data + is transferred over the network. +\end_layout + +\begin_layout Subsection +Audio DSP plugins +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch supports plugins that allows post-processing of audio data, similar + to post-processing of video data. + It supports use of on-the-fly configurable plugins with aid of a GUI. +\end_layout + +\begin_layout Section +Implementing the API +\end_layout + +\begin_layout Standard +The +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro API consists of several functions outlined in libretro.h, found + in the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch source package. + A libretro implementation should be compiled into a dynamically loadable + executable (.dll/.so/.dylib) or a static library (.a/.lib) that exports all + the functions outlined in libretro.h. + These will be called by the frontend. + Implementations are designed to be single-instance, so global state is + allowed. + Should the frontend call these functions in wrong order, undefined behavior + occurs. +\end_layout + +\begin_layout Standard +The API header is compatible with +\begin_inset Index idx +status open + +\begin_layout Plain Layout +C99 +\end_layout + +\end_inset + +C99 and +\begin_inset Index idx +status open + +\begin_layout Plain Layout +C++ +\end_layout + +\end_inset + +C++. + From +\begin_inset Index idx +status open + +\begin_layout Plain Layout +C99 +\end_layout + +\end_inset + +C99, the bool type and are used. +\end_layout + +\begin_layout Standard +The program flow of a frontend using the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro API can be expressed as follows: +\end_layout + +\begin_layout Subsection +Startup +\end_layout + +\begin_layout Subsubsection +retro_api_version() +\end_layout + +\begin_layout Standard +This function should return RETRO_API_VERSION, defined in libretro.h. + It is used by the frontend to determine if ABI/API are mismatched. + The version will be bumped should there be any non- compatible changes + to the API. + Changes to retro_* structures, as well as changes in publically visible + functions and/or their arguments will warrant a bump in API version. +\end_layout + +\begin_layout Subsubsection +retro_init() +\end_layout + +\begin_layout Standard +This function is called once, and gives the implementation a chance to initializ +e data structures. + This is sometimes implemented as a no-op. +\end_layout + +\begin_layout Subsubsection +retro_set_*() +\end_layout + +\begin_layout Standard +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +Libretro is callback based. + The frontend will set all callbacks at this stage, and the implementation + must store these function pointers somewhere. + The frontend can, at a later stage, call these. +\end_layout + +\begin_layout Subsubsection +Environment callback +\end_layout + +\begin_layout Standard +While +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro has callbacks for video, audio and input, there's a callback type + dubbed the environment callback. + This callback (retro_environment_t) is a generic way for the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro implementation to access features of the API that are considered + too obscure to deserve its own symbols. + It can be extended without breaking +\begin_inset Index idx +status open + +\begin_layout Plain Layout +ABI +\end_layout + +\end_inset + +ABI. + The callback has a return type of bool which tells if the frontend recognized + the request given to it. +\end_layout + +\begin_layout Standard +Most implementations of +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro will not use this callback at all. +\end_layout + +\begin_layout Subsubsection +retro_set_controller_port_device() +\end_layout + +\begin_layout Standard +By default, joypads will be assumed to be inserted into the implementation. + If the engine is sensitive to which type of input device is plugged in, + the frontend may call this function to set the device to be used for a + certain player. + The implementation should try to auto-detect this if possible. +\end_layout + +\begin_layout Subsubsection +retro_get_system_info() +\end_layout + +\begin_layout Standard +The frontend will typically request statically known information about the + core such as the name of the implementation, version number, etc. + The information returned should be stored statically. + If dynamic allocation must take place, the implementation must make sure + to free this storage in retro_deinit() later. +\end_layout + +\begin_layout Subsubsection +retro_load_game() +\end_layout + +\begin_layout Standard +This function will load a ROM that the implementation will use to play the + game. + If the implementation is an emulator, this would be a game ROM image, if + it is a game engine, this could be packaged upassets for the game, etc. + The function takes a structure that points to the path where the ROM was + loaded from, as well as a memory chunk of the already loaded file. +\end_layout + +\begin_layout Standard +There are two modes of loading files with libretro. + If the game engine requires to know the path of where the ROM image was + loaded from, the need_fullpath field in retro_system_info must be set to + true. + If the path is required, the frontend will not load the file into the data/size + fields, and it is up to the implementation to load the file from disk. + The path might be both relative and absolute, and the implementation must + check for both cases. +\end_layout + +\begin_layout Standard +This is useful if the ROM image is too large to load into memory at once. + It is also useful if the assests consist of many smaller files, where it + is necessary to know the path of a master file to infer the paths of the + others. + If need_fullpath is set to false, the frontend will load the ROM image + into memory beforehand. + In this mode, the path field is not guaranteed to be non-NULL. + It should point to a valid path if the file was indeed, loaded from disk, + however, it is possible that the file was loaded from stdin, or similar, + which has no well-defined path. +\end_layout + +\begin_layout Standard +It is recommended that need_fullpath is set to false if possible, as it + allows more features, such as soft- patching to work correctly. +\end_layout + +\begin_layout Standard +retro_load_game_special() is a special case of retro_load_game(). + It is designed to allow the loading of several ROMs together. + This is needed for certain odd cases like Super Nintendo with e.g. + Super GameBoy, Sufami Turbo, etc that consist of a "BIOS" + Game(s). + The function takes the type of game as an argument, and if a new game type + is to be added, it needs to be reserved in the libretro.h header. + Almost any libretro implementations should simply implement this as return + false;. + If a game consist of many smaller files it is encouraged to load a single + zipped file, or something similar. +\end_layout + +\begin_layout Standard +Each ROM image can take an optional meta-argument, a string that gives extra + metadeta to the implementation. + The metadata is implementation specific, and can be ignored completely + in almost any implementation. +\end_layout + +\begin_layout Subsubsection +retro_get_system_av_info() +\end_layout + +\begin_layout Standard +This function lets the frontend know essential audio/video properties of + the game. + As this information can depend on the game being loaded, this info will + only be queried after a valid ROM image has been loaded. + It is important to accuractely report FPS and audio sampling rates, as + +\begin_inset Index idx +status open + +\begin_layout Plain Layout +FFmpeg +\end_layout + +\end_inset + +FFmpeg recording relies on exact information to be able to run in sync for + several hours. +\end_layout + +\begin_layout Subsection +Running +\end_layout + +\begin_layout Subsubsection +retro_run() +\end_layout + +\begin_layout Standard +After a game has been loaded successfully, retro_run() will be called repeatedly + as long as the user desires. + When called, the implementation will perform its inner functionality for + one video frame. + During this time, the implementation is free to call callbacks for video + frames, audio samples, as well as polling input, and querying current input + state. + The requirements for the callbacks are that video callback is called exactly + once, i.e. + it does not have to come last. + Also, input polling must be called at least once. +\end_layout + +\begin_layout Subsubsection +Video/Audio synchronization considerations +\end_layout + +\begin_layout Standard +Libretro is based on fixed rates. + Video FPS and audio sampling rates are always assumed to be constant. + Frontends will have control of the speed of playing, typically using VSync + to obtain correctspeed. + The frontend is free to "fast-forward", i.e. + play as fast as possible without waiting, or slow- motion. + For this reason, the engine should not rely on system timers to perform + arbitrary synchronization. + This is common and often needed in 3D games to account for varying frame + rates while still maintaining a playable game. + However, libretro targets classic systems where one can assume that 100 + % real-time performance will always be met, thus avoiding the need for + careful timing code. +\end_layout + +\begin_layout Standard +By default, the libretro implementation should replace any arbitrary sleep()/tim +e() patterns with simply calling video/audio callbacks. + The frontend will make sure to apply the proper synchronization. +\end_layout + +\begin_layout Standard +This is mostly a problem with game ports, such as PrBoom. + For the libretro port of PrBoom, which heavily relied on timers and sleeping + patterns, sleeping was replaced with simply running for one frame, and + calling the video callback. + After that, enough audio was rendered to correspond to one frames worth + of time, 1 / fps seconds. + All sleeping and timing patterns could be removed, and synchronization + was correct. +\end_layout + +\begin_layout Subsubsection +Audio callback considerations +\end_layout + +\begin_layout Standard +The +\begin_inset Index idx +status open + +\begin_layout Plain Layout +libretro +\end_layout + +\end_inset + +libretro API has two different audio callbacks. + Only one of these should be used; the implementation must choose which + callback is best suited. +\end_layout + +\begin_layout Standard +The first audio callback is per-sample, and has the type void (*)(int16_t, + int16_t). + This should be used if the implementation outputs audio on a per-sample + basis. + The frontend will make sure to partition the audio data into suitable chunks + to avoid incurring too much syscall overhead. +\end_layout + +\begin_layout Standard +If audio is output in a "batch" fashion, i.e. + 1 / fps seconds worth of audio data at a time, the batch approach should + be considered. + Rather than looping over all samples and calling per-sample callback every + time, the batch callback should be used instead, size_t (*)(const int16_t + *, size_t). +\end_layout + +\begin_layout Standard +Using the batch callback, audio will not be copied in a temporary buffer, + which can buy a slight performance gain. + Also, all data will be pushed to audio driver in one go, saving some slight + overhead. + It is not recommended to use the batch callback for very small (< 32 frames) + amounts of data. +\end_layout + +\begin_layout Standard +The data passed to the batch callback should, if possible, be aligned to + 16 bytes (depends on platform), to allow accelerated +\begin_inset Index idx +status open + +\begin_layout Plain Layout +SIMD +\end_layout + +\end_inset + +SIMD operations on audio. + +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch implements +\begin_inset Index idx +status open + +\begin_layout Plain Layout +SSE +\end_layout + +\end_inset + +SSE/ +\begin_inset Index idx +status open + +\begin_layout Plain Layout +AltiVec +\end_layout + +\end_inset + +AltiVec optimized audio processing for conversions and resampling. +\end_layout + +\begin_layout Subsubsection +Input device abstraction +\end_layout + +\begin_layout Standard +Abstracting input devices is the hardest part of defining a multi-system + API as it differs across every system. + The common input devices are: +\end_layout + +\begin_layout Itemize +Joypad (with or without analogs) +\end_layout + +\begin_layout Itemize +Mouse (e.g. + SNES mouse) +\end_layout + +\begin_layout Itemize +Keyboard (e.g. + Commodore, Amiga) +\end_layout + +\begin_layout Itemize +Lightguns (e.g. + SNES SuperScope) +\end_layout + +\begin_layout Standard +The joypad abstraction is the most interesting. + Rather than complicating things by mapping input arbitrarily in terms of + the implementation, which would make input configuration very complex with + careful configuration on a per-implementation basis, an abstract joypad + device, the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Input device abstractions!RetroPad +\end_layout + +\end_inset + +RetroPad, was devised. + +\end_layout + +\begin_layout Standard +This joypad is essentially the Super Nintendo controller, widely considered + the pinnacle of retro game controllers. + To account for more modern systems with additional buttons, additions from + the PlayStation DualShock are incorporated, with extra shoulder buttons + (L2/R2), as well as depressable analogs (L3/R3). + In addition, the RETRO_DEVICE_ANALOG is used for analog stick data. + An implementation should map its idea of a joypad in terms of the +\begin_inset Index idx +status open + +\begin_layout Plain Layout +Input device abstractions!RetroPad +\end_layout + +\end_inset + +RetroPad, which is what most users will have to use with their frontend. +\end_layout + +\begin_layout Subsubsection +retro_serialize_size() +\end_layout + +\begin_layout Subsubsection +retro_serialize() +\end_layout + +\begin_layout Subsubsection +retro_unserialize() +\end_layout + +\begin_layout Standard +Serialization is optional to implement. + Serialization is better known as "save states" in emulators, and these + functions are certainly more useful in emulators which have a fixed amount + of state. + It allows the frontend to take a snapshot of all internal state, and later + restore it. + This functionality is used to implement e.g. + rewind and netplay. + Some important considerations must be taken to implement these functions + well. +\end_layout + +\begin_layout Standard +If serialization is not supported, retro_serialize_size() should return + 0. + If retro_serialize_size() returns non-zero, it is assumed that serialization + is properly implemented. +\end_layout + +\begin_layout Standard +The frontend should call retro_serialize_size() before calling retro_serialize() + to determine the amount of memory needed to correctly serialize. + The size eventually passed to retro_serialize() must be at least the size + of the value returned in retro_serialize_size(). + If too large a buffer is passed to retro_serialize(), the extra data should + be ignored (or memset to 0). +\end_layout + +\begin_layout Standard +It is valid for the value returned by retro_serialize_size() to vary over + time, however, it cannot ever increase over time. + If it should ever change, it must decrease. + This is rationaled by the ability to pre- determined a fixed save state + size right after retro_load_game() that will always be large enough to + hold any following serialization. + This certainty is fundamental to the rewind implementation. + This requirement only holds between calls to retro_load_game() and retro_unload +_game(). +\end_layout + +\begin_layout Standard +If possible, the implementation should attempt to serialize data at consistent + offsets in the memory buffer. + This will greatly help the rewind implementation in +\begin_inset Index idx +status open + +\begin_layout Plain Layout +RetroArch +\end_layout + +\end_inset + +RetroArch to use less memory. +\end_layout + +\begin_layout Standard +Both retro_serialize() and retro_unserialize() return a boolean value to + let the frontend know if the implementation succeeded in serializing or + unserializing. +\end_layout + +\begin_layout Subsection +Tear-down +\end_layout + +\begin_layout Subsubsection +retro_unload_game() +\end_layout + +\begin_layout Standard +After the user desired to stop playing, retro_unload_game() will be called. + This should free any internal data related to the game, and allow retro_load_ga +me() to be called again. +\end_layout + +\begin_layout Subsubsection +retro_deinit() +\end_layout + +\begin_layout Standard +This function should free all state that was initialized during retro_init(). + After calling this function, the frontend can again call retro_init(). +\end_layout + +\begin_layout Standard +\begin_inset CommandInset index_print +LatexCommand printindex +type "idx" + +\end_inset + + +\end_layout + +\end_body +\end_document diff --git a/archive/mario-water1.jpg b/archive/mario-water1.jpg new file mode 100644 index 00000000..37053eda Binary files /dev/null and b/archive/mario-water1.jpg differ diff --git a/archive/mario-water2.jpg b/archive/mario-water2.jpg new file mode 100644 index 00000000..ba307f64 Binary files /dev/null and b/archive/mario-water2.jpg differ diff --git a/archive/overlay.tex b/archive/overlay.tex new file mode 100644 index 00000000..5f30a4cb --- /dev/null +++ b/archive/overlay.tex @@ -0,0 +1,115 @@ +\documentclass[a4paper, 11pt]{article} + +\title{RetroArch - Overlay image configuration} +\author{ +Hans-Kristian Arntzen +\and +Daniel De Matteis} + +\begin{document} +\maketitle + +\section*{Purpose} + +RetroArch supports overlay images for use with hardware accelerated drivers. +The purpose of this is to allow some kind of input interface that is mouse/touch oriented. + +The overlay image is displayed with transparency over the regular game image, and the user is able to trigger input by pressing on certain parts of the overlay. + +Since the overlay is an image, the user should be able to fully configure the look and functionality of this overlay. This allows skinners and themers to go wild. + +\section*{Configuration} + +The overlay is described in a config file (*.cfg). The config file uses the same config file syntax as RetroArch itself. + +The overlay system supports use of multiple overlays that can be switched out on the fly. Input is not only restricted to gamepad input, but can also work with any input that is bindable in RetroArch, e.g. save states, rewind, load state, etc. + +The config file describes: +\begin{itemize} + \item Which overlay images to use (.png, .tga, etc). + \item Which coordinates on each overlay correspond to which input event. + \item The hitbox for each input event, i.e. "size" of the button. + \item Where on the screen the overlay should be displayed. +\end{itemize} + + +\subsection*{Overlay images} + +First we configure how many overlays we use, and where they can be found. + +\begin{verbatim} + overlays = 2 + overlay0_overlay = overlay_img0.png + overlay1_overlay = overlay_img1.png +\end{verbatim} + +The paths are relative to where the overlay config is loaded from. If the path is absolute, absolute paths will be used. On Unix-like systems '~/' is recognized as '\$HOME'. + +\subsection*{Screen placement} + +By default, the overlay image will be stretched out to fill the whole game image. +However, for some overlays, this is not practical. + +It is possible to set the placement using for example: + +\begin{verbatim} + overlay0_rect = "0.2,0.3,0.5,0.4" +\end{verbatim} + +We assume that the game screen has normalized coordinates in X and Y that span from `[0, 0]` +in the top-left corner to $[1, 1]$ in the lower-right corner. + +This will render the overlay to $x = 0.2, y = 0.3$ with size $width = 0.5, height = 0.4$. +The default (stretch to full screen) could be described as such: + +\begin{verbatim} + overlay0_rect = "0.0,0.0,1.0,1.0" +\end{verbatim} + +\subsection*{Full-screen overlays} + +By default, overlays will be stretched out to fill game viewport. However, in some cases +the aspect ratio of the game causes there to remain large black borders around the game image. +It is possible to stretch the overlay to full screen (instead of viewport) by specifying this option: + +\begin{verbatim} + overlay0_full_screen = true +\end{verbatim} + +\subsection*{Coordinate descriptors} + +We must also describe where on the overlay image buttons can be found for each overlay. +E.g.: + +\begin{verbatim} + overlay0_descs = 3 # Three buttons for this overlay in total + overlay0_desc0 = "a,32,64,radial,10,20" + overlay0_desc1 = "start,100,50,rect,80,10" + overlay0_desc2 = "overlay_next,200,180,radial,40,40" +\end{verbatim} + +The format is: + +\begin{verbatim} + "button,position_x,position_y,hitbox_type,range_x,range_y" +\end{verbatim} + +'button' corresponds to the input event being generated. The names are the same as in the general input config, e.g. input\_player1\_start would translate to start here. overlay\_next is a special bind designed to swap to the next overlay, or wrap around to the first one. + +'position\_x' and 'position\_y' are the x and y coordinates in pixels of the source image for the center of the button. + +'hitbox\_type' describes which type of shape the button has. 'radial' (circle, ellipsis) and 'rect' (rectangular) shapes are supported. + +'range\_x' and 'range\_y' describe the size of the button. The semantics differ slightly for radial and rect hitbox types. For 'radial' shape, 'range\_x' and 'range\_y' describe the radius in x and y directions in pixels of the source image. For 'rect' shape, the 'range\_x' and 'range\_y' values represent the distance from center to the edge of the rect in terms of pixels of the source image. E.g. a 'range\_x' of 20 would mean the width of the rectangular is 40 pixels in total. + +\subsection*{Triggering multiple buttons with one desc} + +It's possible to trigger multiple buttons (e.g. diagonals) with one overlay desc. + +\begin{verbatim} + overlay0_desc0 = "left|up,32,64,radial,10,20" +\end{verbatim} + +will trigger both left and up at same time. + +\end{document} \ No newline at end of file diff --git a/archive/ratecontrol-data.pdf b/archive/ratecontrol-data.pdf new file mode 100644 index 00000000..c04b86f4 Binary files /dev/null and b/archive/ratecontrol-data.pdf differ diff --git a/archive/ratecontrol.tex b/archive/ratecontrol.tex new file mode 100644 index 00000000..6f48b45e --- /dev/null +++ b/archive/ratecontrol.tex @@ -0,0 +1,211 @@ +\documentclass[11pt, a4paper]{article} + +\title{Dynamic Rate Control for Retro Game Emulators} +\author{Hans-Kristian Arntzen} + +\usepackage{amsmath} +\usepackage{float} +\usepackage{graphicx} + +\begin{document} +\maketitle + +\begin{abstract} +This article describes a method for game emulator frontends +to synchronize both audio and video output at the same time, even +when the emulating system has a different refresh rate and audio sampling rate +than the gaming system that is being emulated. + +The method works by dynamically adjusting audio resampling ratios in such ways that +ideally, the audio buffer is never underrun nor overrun, thus avoiding blocking on audio. +This in turn allows vertical synchronization for video. + +The audio pitch is adjusted when adjusting audio resampling ratios, +but in practice so little, that it is inaudible to the human ear. +\end{abstract} + +\section{Background} + +Retro game consoles are highly synchronous. Their audio output rates are linked directly +to video refresh rates. Every video frame, the audio chip generates on average a fixed amount of audio samples. Before continuing to emulate the next frame, the generated audio samples must be pushed +to an audio buffer of fixed size. + +If there is not enough space in the audio buffer, the emulator must wait (block) for the buffer to become ready for writing. This is a non-ideal situation as while the emulator is blocking on audio, a vertical refresh might be missed entirely, thus creating stuttering video. + +\subsection{The ideal synchronization} +For an emulator of a retro game system, a key factor in smooth video is vertical refresh synchronization (VSync), where each frame of the game maps to a single frame on the monitor. +Audio must also be pushed to the speakers without any audio dropouts. +This double synchronization requirement poses a problem as any form of synchronization to one modality +will negatively affect the other. + +This is a real problem as an emulator has no way of guaranteeing perfectly equal +video refresh rates and audio sampling rates as the original system. + +On conventional computer hardware, there is no perfect way of knowing +the real monitor refresh rates and audio sampling rates either due to +tolerances on oscillators. + +\subsection{Scope of method} +As this method aims to implement a method for synchronization when VSync is used, +this method is only useful when game frame rate is close to monitor frame rate. +If this is not the case, other methods should be employed. + +\section{Method} +This method assumes that audio from the emulator is output at regular intervals, e.g. +every video frame. The method also assumes that audio is resampled from +the game system sampling rate to the sound cards sampling rate. +The resampling ratio will be dynamically adjusted every time audio is resampled and subsequently pushed to the audio buffer. + +\subsection{Definitions} +\begin{itemize} +\item[$f_v$] Emulated game system frame rate (FPS) +\item[$f_a$] Emulated game system sampling rate (Hz) +\item[$r$] Emulated game system samples per frame $f_a / f_v$ +\item[$m_a$] Emulator system sampling rate +\item[$m_v$] Emulator system monitor refresh rate +\item[$m_a^{'}$] Estimated emulator system sampling rate +\item[$m_v^{'}$] Estimated emulator system monitor refresh rate +\item[$R$] Emulator system samples per frame $m_a / m_v$ +\item[$R^{'}$] Estimated emulator system samples per frame $m_a^{'} / m_v^{'}$ +\item[$A_b$] Current amount of samples in the audio buffer +\item[$A_B$] Capacity (in samples) of the audio buffer +\item[$d$] Allowed deviation in audio pitch +\end{itemize} + +\subsection{Resampling audio} +Every time the game system outputs audio, it is resampled with some ratio. +It is here assumed that the game system outputs a video frame worth of audio at a time. +While the formulae are invariant to how often audio is written to audio buffers, this assumption +is made for simplicity. + +The correct resampling ratio is estimated to be $R^{'} / r$, +thus pushing $R^{'}$ samples of audio per frame on average. +In the duration of a frame, on average, $R$ audio frames will have been played to the speakers +and thus removed from the buffer. + +\begin{equation} +\Delta A_b = R^{'} - R +\end{equation} + +We see that unless $\Delta A_b = 0$, it is inevitable that the audio will either underrun ($A_b \leq 0$), +or block due to buffer being full ($A_b \geq A_B$). +Both these situations are not acceptable as underruns would cause audible audio dropouts, +and blocking would block the emulator from emulating more frames, and thus greatly increasing the chance of missing a VBlank, which is not acceptable as well. Blocking however, is far more preferable than underrunning. + +As with any estimator, it is impossible to guarantee that $R^{'}$ can be perfectly estimated. +Therefore, it is impossible to guarantee that underrun nor blocking occurs. + +\subsection{Dynamic rate control} +The proposed method will dynamically adjust the resampling ratio $R^{'} / r$. +Changing this ratio will adjust audio pitch as well. To ensure that these adjustments are not audible to the human ear, the range of adjustment will be limited by $d$. + +Using $d$, the maximum pushed samples will be $R^{'} \left(1 + d\right)$, +and similarly, minimum will be $R^{'} \left(1 - d\right)$. +$d$ must be chosen so that $R$ falls between minimum or maximum. This depends on the confidence of the estimate $R^{'}$. + +The revised update formula will look like this: + +\begin{equation} \label{eq:update} +\Delta A_b = \left[ 1 + \left(\frac{A_B - 2A_b}{A_B}\right) d \right] R^{'} - R +\end{equation} + +The formula will decrease resampling ratio if audio buffer is over half full, and similarly increase +resampling ratio if buffer is below half full. + +\subsection{Stability} + +To ensure that the method is stable, i.e. that $A_b$ will converge to a certain value, +we assume a continuous model for pushing audio. + +\begin{equation} +\frac{\delta A_b}{\delta f} = \left[ 1 + \left(\frac{A_B - 2A_b}{A_B}\right) d \right] R^{'} - R +\end{equation} +\begin{equation} \label{eq:ab-diff} +\frac{\delta A_b}{\delta f} + \frac{2dR^{'}}{A_B}A_b = R^{'} \left(1 + d\right) - R +\end{equation} + +The differential equation in \eqref{eq:ab-diff} can be solved as + +\begin{equation} +A_b = A_B \frac{R^{'}\left(1 + d\right) - R}{2dR^{'}} + C_0\exp \left(-\frac{2dR^{'}}{A_B} f\right) +\end{equation} + +Given time ($f \rightarrow \infty$), this expression converges to + +\begin{equation} +A_{b,c} = A_B \frac{R^{'}\left(1 + d\right) - R}{2dR^{'}} +\end{equation} + +If $R^{'}$ is the ideal estimate, $R^{'} = R$, the expression converges to + +\begin{equation} +A_{b,c} = A_B / 2 +\end{equation} +which is the best case, as having a half full buffer means most possible wiggle room for jitter. + +\subsection{Updating ratio estimate $R^{'}$} +After time, it is assumed that $A_b$ will converge to $A_{b,c}$. +Due to jitter, and various non-ideal behavior, only an estimate of $A_{b,c}$, $\hat{A_{b,c}} = \bar{A_b}$ can be obtained. + +\begin{equation} +\frac{\hat{R^{'}}}{R} = \frac{A_B}{\left(1 + d\right) A_B - 2d\hat{A_{b,c}}} +\end{equation} + +The ratio estimate $R^{'}$ can thus be re-estimated accordingly. This method of re-estimating the ratio might however not be the best. Directly estimating $m_a^{'}$ and $m_v^{'}$ should yield more confident results, but this is outside the scope of this article. + +\section{Results} + +A synthetic test was carried out to test how the method would react to a common scenario for this method. An emulation of Super Nintendo Entertainment System (SNES) was matched to an emulating system. +To test effects of jitter, the frame time was assumed to follow a normal distribution. +Thus, $R$ in \eqref{eq:update} followed a normal distribution. + +\begin{table}[H] +\centering +\caption{Timings} +\begin{tabular}{|c|c|c|} + \hline + System & FPS (Hz) & Sample rate (Hz)\\\hline + SNES & 60.0988 & 32040.5\\\hline + Emulating system & 59.88 & 48000.15\\\hline + Estimated system & 59.95 & 48000.0\\\hline +\end{tabular} +\end{table} + +\begin{table}[H] +\centering +\caption{Test parameters} +\begin{tabular}{|c|c|} + \hline + $d$ & $0.005$\\\hline + Frame time deviation & $2 \%$\\\hline +\end{tabular} +\end{table} + +\begin{figure}[H] +\centering +\includegraphics[width=12cm]{ratecontrol-data.pdf} +\caption{Results with 2\% standard deviation on frame time} +\end{figure} + +The results are shown for audio buffer size over time and the pitch modulation for every simulated frame. Audio pitch modulation deviation was estimated to $0.062\%$, significantly lower than the $d$ value, which allowed for a maximum deviation of $0.5\%$. + +The audio buffer is never filled nor underrun, which would allow every single VBlank to be met, while maintaining audio sync. + +\section{Discussion} + +\subsection{Effect of $d$} +Ideally, $d$ should be as low as possible to avoid large deviations in pitch, but at the same time, a too low value for $d$ will not be able to compensate for the difference between $R^{'}$ and $R$. +From testing in the emulator frontend RetroArch\footnote{https://github.com/Themaister/RetroArch}, a factor of $d \geq 0.002, d \leq 0.005$ has been found to give satisfactory results. + +This method does not propose a method of determining the best $d$ factor. + +\subsection{Audibility} +As audio pitch is altered, there is a question of audibility. Given a small enough $d$, it's +clear that the effect would be completely inaudible as all oscillators in a DAC have tolerances and jitter to some degree. It is also reasonable to believe that some persons are able to notice a smaller $d$ than others. + +Some testing must be carried out to find a $d$ that is inaudible in subjective tests. + +\section{Conclusion} +This method shows that it is possible to obtain synchronization to both VBlank and audio without having a perfect estimate of the emulating systems frequencies. As long as the estimates are reasonable close to the real values, the dynamic rate control method proposed here is able to smooth out the differences. + +\end{document} \ No newline at end of file diff --git a/archive/retroarch-cores-manual.lyx b/archive/retroarch-cores-manual.lyx new file mode 100644 index 00000000..41083811 --- /dev/null +++ b/archive/retroarch-cores-manual.lyx @@ -0,0 +1,2002 @@ +#LyX 2.0 created this file. For more info see http://www.lyx.org/ +\lyxformat 413 +\begin_document +\begin_header +\textclass article +\use_default_options true +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding auto +\fontencoding global +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 + +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\spacing single +\use_hyperref true +\pdf_title "RetroArch Cores Manual" +\pdf_author "Hans-Kristian Antzen, Daniel De Matteis" +\pdf_bookmarks true +\pdf_bookmarksnumbered false +\pdf_bookmarksopen false +\pdf_bookmarksopenlevel 1 +\pdf_breaklinks false +\pdf_pdfborder false +\pdf_colorlinks true +\pdf_backref false +\pdf_pdfusetitle true +\papersize default +\use_geometry false +\use_amsmath 1 +\use_esint 1 +\use_mhchem 1 +\use_mathdots 1 +\cite_engine basic +\use_bibtopic false +\use_indices false +\paperorientation portrait +\suppress_date false +\use_refstyle 1 +\index Index +\shortcut idx +\color #008000 +\end_index +\secnumdepth 5 +\tocdepth 5 +\paragraph_separation indent +\paragraph_indentation default +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/logo.png + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Title +RetroArch Android (v0.9.8.4) - Cores Manual +\end_layout + +\begin_layout Author +Hans Kristian Arntzen, Daniel De Matteis +\end_layout + +\begin_layout Standard +\begin_inset CommandInset toc +LatexCommand tableofcontents + +\end_inset + + +\end_layout + +\begin_layout Section +Introduction +\end_layout + +\begin_layout Standard +Listed below are all the cores that RetroArch Android supports. +\end_layout + +\begin_layout Itemize +SNES9x Next +\begin_inset Newline newline +\end_inset + +Used for: playing SNES games (Super Nintendo Entertainment System) +\begin_inset Newline newline +\end_inset + +Author(s): SNES9x team, OV2, Bearoso, zones, Squarepusher (fork) +\begin_inset Newline newline +\end_inset + +Recommended system requirements: ARM Cortex A9 multi-core device (and up) +\begin_inset Newline newline +\end_inset + +Extensions: "smc|fig|sfc|gd3|gd7|dx2|bsx|swc|zip|SMC|FIG| +\begin_inset Newline newline +\end_inset + +SFC|BSX|GD3|GD7|DX2|SWC|ZIP" +\end_layout + +\begin_layout Itemize +VBA Next +\begin_inset Newline newline +\end_inset + +Used for: playing Game Boy Advance games +\begin_inset Newline newline +\end_inset + +Recommended system requirements: ARM Cortex A9 multi-core based device (and + up) +\begin_inset Newline newline +\end_inset + +Author(s): Forgotten, VBA-M team, Squarepusher (fork) +\begin_inset Newline newline +\end_inset + +Extensions: "gba|GBA|zip|ZIP" +\end_layout + +\begin_layout Itemize +FCEUmm +\begin_inset Newline newline +\end_inset + +Used for: playing NES games (Nintendo Entertainment System) +\begin_inset Newline newline +\end_inset + +Author(s): CaH4e3, original FCEU authors +\begin_inset Newline newline +\end_inset + +Extensions: "fds|FDS|zip|ZIP|nes|NES|unif|UNIF" +\end_layout + +\begin_layout Itemize +NEStopia +\begin_inset Newline newline +\end_inset + +Used for: playing NES games (Nintendo Entertainment System) +\begin_inset Newline newline +\end_inset + +Author(s): Marty +\begin_inset Newline newline +\end_inset + +Extensions supported: "nes|NES|zip|ZIP|fds|FDS" +\end_layout + +\begin_layout Itemize +Gambatte +\begin_inset Newline newline +\end_inset + +Used for: playing GameBoy / GameBoy Color games +\begin_inset Newline newline +\end_inset + +Author(s): Sinamas +\begin_inset Newline newline +\end_inset + +Extensions supported: "gb|gbc|dmg|zip|GB|GBC|DMG|ZIP" +\end_layout + +\begin_layout Itemize +Final Burn Alpha +\begin_inset Newline newline +\end_inset + +Used for: playing arcade games +\begin_inset Newline newline +\end_inset + +Author(s): Dave, FBA Team (Barry Harris & co) +\begin_inset Newline newline +\end_inset + +Extensions supported: +\begin_inset Quotes eld +\end_inset + +zip|ZIP +\begin_inset Quotes erd +\end_inset + + +\end_layout + +\begin_layout Itemize +Genesis Plus GX +\begin_inset Newline newline +\end_inset + +Used for: playing Sega Genesis / Master System / Game Gear / Sega CD games +\begin_inset Newline newline +\end_inset + +Author(s): Charles McDonald, ekeeke +\begin_inset Newline newline +\end_inset + +Extensions supported: "md|smd|bin|cue|gen|zip|MD|SMD|bin|iso| +\begin_inset Newline newline +\end_inset + +ISO|CUE|GEN|ZIP|sms|SMS|gg|GG|sg|SG" +\end_layout + +\begin_layout Itemize +NX Engine +\begin_inset Newline newline +\end_inset + +Used for: playing Cave Story / Doukutsu Monogatari +\begin_inset Newline newline +\end_inset + +Author(s): Caitlin Shaw (rogueeve) +\begin_inset Newline newline +\end_inset + +Extensions supported: +\begin_inset Quotes eld +\end_inset + +exe|EXE|zip|ZIP +\begin_inset Quotes erd +\end_inset + + +\end_layout + +\begin_layout Itemize +PCSX ReARMed +\begin_inset Newline newline +\end_inset + +Used for: playing PlayStation1 games +\begin_inset Newline newline +\end_inset + +Author(s): PCSX Team, Notaz, Exophase (GPU plugin) +\begin_inset Newline newline +\end_inset + +Extensions supported: "bin|cue|img|mdf|pbp|cbn" +\end_layout + +\begin_layout Itemize +Prboom +\begin_inset Newline newline +\end_inset + +Used for: playing Doom, Doom 2, Ultimate Doom, Final Doom, and mods +\begin_inset Newline newline +\end_inset + +Author(s): Various +\begin_inset Newline newline +\end_inset + +Extensions supported: "WAD|wad|IWAD|iwad" +\end_layout + +\begin_layout Itemize +Mednafen NGP +\begin_inset Newline newline +\end_inset + +Used for: playing Neo Geo Pocket Color games +\begin_inset Newline newline +\end_inset + +Author(s): Original Neopop authors, Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "ngp|NGP|ngc|NGC|zip|ZIP" +\end_layout + +\begin_layout Itemize +Mednafen WonderSwan +\begin_inset Newline newline +\end_inset + +Used for: playing WonderSwan / WonderSwan Color / WonderSwan Crystal games +\begin_inset Newline newline +\end_inset + +Author(s): Original Cygne authors, Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "ws|WS|wsc|WSC|zip|ZIP" +\end_layout + +\begin_layout Itemize +Mednafen Virtual Boy +\begin_inset Newline newline +\end_inset + +Used for: playing Virtual Boy games +\begin_inset Newline newline +\end_inset + +Author: Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "vb|VB|vboy|VBOY|bin|BIN|zip|ZIP" +\end_layout + +\begin_layout Itemize +Mednafen PC Engine +\begin_inset Newline newline +\end_inset + +Used for: playing PC Engine / Supergrafx 16 / PC Engine CD games +\begin_inset Newline newline +\end_inset + +Author: Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "pce|PCE|sgx|SGX|cue|CUE|zip|ZIP" +\end_layout + +\begin_layout Standard +We'll go over each of these. +\end_layout + +\begin_layout Subsection +SNES9x Next +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} +\end_layout + +\end_inset + + v1.52.3 +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator should run at fullspeed on an Android device with a dual-core + ARM Cortex A9-based CPU. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{v1.52.4} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Speed optimizations for Star Fox 1 / Star Wing - now makes them fast enough + for fullspeed gameplay on Wii. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{v1.52.3} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Fixed DKC2 graphics inaccuracies +\end_layout + +\begin_layout Itemize +Fixed issue that could corrupt memory addresses over time - found while + deiniting Super Mario Kart. +\end_layout + +\begin_layout Itemize +Updated to use RGB565 as pixel format. +\end_layout + +\begin_layout Itemize +Speed hacks for Final Fantasy III/VI - makes it fullspeed for Wii. +\end_layout + +\begin_layout Itemize +Fixed Super Double Dragon input issue. +\end_layout + +\begin_layout Subsection +VBA Next +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} +\end_layout + +\end_inset + + v1.0.2 +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator needs at least a dual-core ARM Cortex A9-based CPU and up. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{v1.0.2} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Added Pokemon Emerald to built-in vbaover - fixes white screen +\end_layout + +\begin_layout Itemize +Lessens RAM footprint - makes Mother 3 fit into memory on Wii. +\end_layout + +\begin_layout Itemize +More consistent syncing. +\end_layout + +\begin_layout Itemize +Updated to use RGB565 as pixel format. +\end_layout + +\begin_layout Subsection +FCEUmm +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 98.13 SVN +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co +re CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Upgraded to latest SVN (r134) +\end_layout + +\begin_layout Itemize +Updated to use RGB565 as pixel format. +\end_layout + +\begin_layout Subsection +NEStopia +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 1.44 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co +re CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +There might still be an audio desync that happen at the half hour mark. + Ever since NEStopia 1.36 some kind of APU bug has been inadvertently introduced. + We will be researching this. +\end_layout + +\begin_layout Itemize +For Famicom Disk System games - Y Button will switch sides of a disk. + - If you get any problems of the sort DISK A / B ERR 07' - pressing Y button + again or letting it run its course should do it. +\end_layout + +\begin_layout Itemize +Famicom Disk System loading is slow, so you might be tempted to fast forward + through most of it. + However, I'd advise caution when doing so and to savestate regularly in + case 'fast forwarding' can negatively affect disk loading. + +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8.3 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Famicom Disk System support. + For Android users - put disksys.rom into the same folder as the FDS ROM + you're trying to load. + For everyone else - put disksys.rom into your system directory. + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +New port +\end_layout + +\begin_layout Subsection +Gambatte +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 0.50 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co +re CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Now makes use of GBC BIOS color palettes. +\end_layout + +\begin_layout Itemize +Can also make use of custom color palettes. +\end_layout + +\begin_layout Itemize +Updated to use RGBX8888 as pixel format. +\end_layout + +\begin_layout Subsection +Final Burn Alpha +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 0.2.97.28 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + Performance varies based on the game you're trying to play. + Systems like CPS2 and Neogeo have been tested to run at fullspeed on an + ARM Cortex A8 single-core CPU. + CPS3 needs a dual-core ARM Cortex A9-based CPU for fullspeed gameplay. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +Some games might be stuck in Service mode right now on big-endian systems + (ie. + PS3/360/Wii). + Some games that come to mind are Psikyo SH2 games and Taito games like + Darius 2. + We will be trying to fix this issue soon and release a point update for + it. +\end_layout + +\begin_layout Itemize +Button combos ingame: +\end_layout + +\begin_layout Itemize +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Select = Service Menu + button +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Start = Diagnostic + button +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Left = Reset button +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Right = DIP A Pressed +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Up = DIP B Pressed +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Down = Test Pressed +\end_layout + +\begin_layout Itemize +Savestates are hooked up but games can't have their 'state restored' after + unloading the game and loading it again. +\end_layout + +\begin_layout Itemize +If you want to play Warzard or Red Earth and you happen to get a 'No CD-ROM + drive' message - do the 'Reset' combo (see above) - it should work then. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Upgraded to 0.2.97.28. +\end_layout + +\begin_layout Itemize +Controls have been revised - most of the controls should now be properly + hooked up. +\end_layout + +\begin_layout Itemize +Button combos have been changed - +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Select = Service Menu + button +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Start = Diagnostic + button +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Left = Reset button +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Right = DIP A Pressed +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Up = DIP B Pressed +\begin_inset Newline newline +\end_inset + +RetroPad L2 + RetroPad R2 + RetroPad L + RetroPad R + Down = Test Pressed +\end_layout + +\begin_layout Itemize +Uses RGBX8888 as a color format for Psikyo SH2 games and RGB565 for everything + else. +\end_layout + +\begin_layout Subsection +Genesis Plus GX +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 1.7.3 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run regular Genesis and Sega CD games + at fullspeed on an ARM Cortex A8 single-core CPU. + Virtua Racing runs at half realtime speed on the same hardware and thus + needs better system requirements. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +FOR ANDROID: To play Sega CD/Mega CD games, you will need Sega CD BIOS files + in the same directory as the game you want to play. + They should be named as follows: bios_CD_E.bin (for EU BIOS), bios_CD_U.bin + (for US BIOS), bios_CD_J.bin (for Japanese BIOS) +\end_layout + +\begin_layout Itemize +FOR EVERYTHING ELSE: To play Sega CD/Mega CD games, you will need Sega CD + BIOS files in the same directory as the game you want to play. + They should be named as follows: bios_CD_E.bin (for EU BIOS), bios_CD_U.bin + (for US BIOS), bios_CD_J.bin (for Japanese BIOS). +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Upgraded to 1.7.3 ( might report 1.7.1 but is really 1.7.3). +\end_layout + +\begin_layout Itemize +Updated to use RGB565. +\end_layout + +\begin_layout Subsection +NX Engine +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 1.0.4 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This game has been tested to run at fullspeed on an ARM Cortex A8 single-core + CPU. + Sound syncing however is currently not correct. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +HOW TO USE +\end_layout + +\begin_layout Standard +You need to copy all the 'datafiles' directory in the repository over. + Start the core with doukutsu.exe - it should properly extract the needed + archives from the EXE on initial boot. + From there on it will use those extracted asset files. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +NXEngine is not released yet on consoles - sound is currently corrupt on + big-endian consoles (Xbox 1/360/PS3/Wii). + Will need to research what is up here. +\end_layout + +\begin_layout Itemize +Savestates are not hooked up - therefore rewind is also not possible. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Upgraded to 1.0.4. +\end_layout + +\begin_layout Itemize +Did major changes to path handling code and got rid of the hardcoded paths + - should now handle paths correctly on _WIN32 targets. +\end_layout + +\begin_layout Itemize +Fixed save files not working. +\end_layout + +\begin_layout Itemize +Updated to use RGB565. +\end_layout + +\begin_layout Subsection +PCSX ReARMed +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} r18 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run most games at fullspeed on an ARM + Cortex A8 single-core CPU. + Higher-resolution interlaced games like Tekken 3 and Tobal 2 require higher + system specs (Cortex A9 and up). + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +PCSX ReARMed supports the loading of EBOOT (pbp) files as well. +\end_layout + +\begin_layout Itemize +Although PCSX ReARMed comes with built-in HLE BIOS code, you're recommended + to still put BIOS files in the system directory (on Android there is no + 'system directory', so instead you put the BIOS files in the same directory + as the image you're trying to load). + Some of the BIOS files used are: scph1001.bin, scph5500.bin, scph5501.bin, + scph5502.bin, scph7502.bin. +\end_layout + +\begin_layout Itemize +If an image might not load correctly, try it with and without BIOS files + in the 'system directory' (read above note about 'system directory' as + well). +\end_layout + +\begin_layout Itemize +This is an ARM architecture-centric port right now - it is not of much use + on other architectures and therefore consoles. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +New port. +\end_layout + +\begin_layout Subsection +Prboom +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 2.5.0 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This game engine has been tested to run most games at fullspeed on an ARM + Cortex A8 single-core CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +You need to have prboom.wad in the same directory as the Doom WAD file you're + going to load. +\end_layout + +\begin_layout Itemize +Savestates are currently not hooked up, and therefore rewind is not possible. +\end_layout + +\begin_layout Itemize +Re-entrancy does not work correctly yet - don't try to load a second WAD + file. + Instead, exit prboom first and then launch it again (only applies to consoles). +\end_layout + +\begin_layout Itemize +This is the only Doom port in existence right now where you have the option + to play at variable framerates. + The option exists to play at 35, 40, 50 and 60fps. + Doom originally ran at 35fps due to performance reasons and the slow CPUs + available at the time. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Now uses RGB565 as pixel format. +\end_layout + +\begin_layout Subsubsection +SOUNDTRACK LIST +\end_layout + +\begin_layout Standard +Prboom supports MP3 soundtracks. + The files must be in the same directory as the WAD file and should be correctly + named. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{ +\backslash +break} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +DOOM 1 +\end_layout + +\begin_layout Standard +e1m1.mp3 +\end_layout + +\begin_layout Standard +e1m2.mp3 +\end_layout + +\begin_layout Standard +e1m3.mp3 +\end_layout + +\begin_layout Standard +e1m4.mp3 +\end_layout + +\begin_layout Standard +e1m5.mp3 +\end_layout + +\begin_layout Standard +e1m6.mp3 +\end_layout + +\begin_layout Standard +e1m7.mp3 +\end_layout + +\begin_layout Standard +e1m8.mp3 +\end_layout + +\begin_layout Standard +e1m9.mp3 +\end_layout + +\begin_layout Standard +e2m1.mp3 +\end_layout + +\begin_layout Standard +e2m2.mp3 +\end_layout + +\begin_layout Standard +e2m3.mp3 +\end_layout + +\begin_layout Standard +e2m4.mp3 +\end_layout + +\begin_layout Standard +e2m5.mp3 +\end_layout + +\begin_layout Standard +e2m6.mp3 +\end_layout + +\begin_layout Standard +e2m7.mp3 +\end_layout + +\begin_layout Standard +e2m8.mp3 +\end_layout + +\begin_layout Standard +e2m9.mp3 +\end_layout + +\begin_layout Standard +e3m1.mp3 +\end_layout + +\begin_layout Standard +e3m2.mp3 +\end_layout + +\begin_layout Standard +e3m3.mp3 +\end_layout + +\begin_layout Standard +e3m4.mp3 +\end_layout + +\begin_layout Standard +e3m5.mp3 +\end_layout + +\begin_layout Standard +e3m6.mp3 +\end_layout + +\begin_layout Standard +e3m7.mp3 +\end_layout + +\begin_layout Standard +e3m8.mp3 +\end_layout + +\begin_layout Standard +intermid1.mp3 +\end_layout + +\begin_layout Standard +intro.mp3 +\end_layout + +\begin_layout Standard +bunny.mp3 +\end_layout + +\begin_layout Standard +victor.mp3 +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{ +\backslash +break} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +DOOM 2 +\end_layout + +\begin_layout Standard +stalks.mp3 +\end_layout + +\begin_layout Standard +runnin.mp3 +\end_layout + +\begin_layout Standard +countd.mp3 +\end_layout + +\begin_layout Standard +betwee.mp3 +\end_layout + +\begin_layout Standard +doom.mp3 +\end_layout + +\begin_layout Standard +the_da.mp3 +\end_layout + +\begin_layout Standard +shawn.mp3 +\end_layout + +\begin_layout Standard +ddtblu.mp3 +\end_layout + +\begin_layout Standard +in_cit.mp3 +\end_layout + +\begin_layout Standard +dead.mp3 +\end_layout + +\begin_layout Standard +romero.mp3 +\end_layout + +\begin_layout Standard +messag.mp3 +\end_layout + +\begin_layout Standard +ampie.mp3 +\end_layout + +\begin_layout Standard +tense.mp3 +\end_layout + +\begin_layout Standard +openin.mp3 +\end_layout + +\begin_layout Standard +evil.mp3 +\end_layout + +\begin_layout Standard +ultima.mp3 +\end_layout + +\begin_layout Standard +read_m.mp3 +\end_layout + +\begin_layout Standard +dm2ttl.mp3 +\end_layout + +\begin_layout Standard +dm2int.mp3 +\end_layout + +\begin_layout Subsection +Mednafen NGP +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 0.9.28 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co +re CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +New port. +\end_layout + +\begin_layout Subsection +Mednafen Wonderswan +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 0.9.28 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co +re CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +The music is incorrect on Xbox 360. + This seems to be a 360-specific bug. +\end_layout + +\begin_layout Itemize +Because Wonderswan has a 75Hz refresh rate, V-sync is specifically disabled + for this core so that the framerate and sound is as it should be - that's + why you might notice some negligible tearing. + +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Upgraded to 0.9.28 version. +\end_layout + +\begin_layout Itemize +Fixes save file issues on MSVC-based consoles (Xbox 1/360). +\end_layout + +\begin_layout Itemize +Now uses RGB565 as a pixel format. +\end_layout + +\begin_layout Subsection +Mednafen Virtual Boy +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 0.9.28 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + You will need at least a Cortex A9 CPU and/or higher for this. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +This is not released yet for Xbox 1 and 360 because there are numerous game + compatibility-breaking issues right now. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +New port. +\end_layout + +\begin_layout Subsection +Mednafen PC Engine +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Version:} 0.9.28 +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Android performance:} +\end_layout + +\end_inset + + This emulator has been tested to run at fullspeed on an ARM Cortex A8 single-co +re CPU. + Your mileage may vary on slower devices. +\end_layout + +\begin_layout Subsubsection +NOTES +\end_layout + +\begin_layout Itemize +FOR ANDROID USERS: +\begin_inset space ~ +\end_inset + +You will need a BIOS file called 'syscard3.pce' placed in the same directory + as the ISO/CUE you want to play to be able to play PC Engine CD games. +\end_layout + +\begin_layout Itemize +FOR ANYBODY ELSE: You will need a BIOS file called 'syscard3.pce' in your + system directory in order to be able to play PC Engine CD games. +\end_layout + +\begin_layout Subsubsection +CHANGELOG +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{For 0.9.8 point release} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Upgraded to 0.9.28. +\end_layout + +\begin_layout Itemize +Fixes save file issues on MSVC-based consoles (Xbox 1/360). +\end_layout + +\begin_layout Itemize +Updated to use RGB565 as pixel format. +\end_layout + +\begin_layout Section +About Us +\end_layout + +\begin_layout Standard +Homepage: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +http://www.libretro.org +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +IRC: #retroarch at freenode +\begin_inset Newline newline +\end_inset + +Github (libretro organization): +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://github.com/libretro +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +RetroArch @ Github: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://github.com/Themaister/RetroArch +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +Libretro @ Twitter: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://twitter.com/libretro +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +Libretro @ Facebook: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://www.facebook.com/libretro.retroarch +\end_layout + +\end_inset + + +\end_layout + +\end_body +\end_document diff --git a/archive/retroarch-enduserguide.lyx b/archive/retroarch-enduserguide.lyx new file mode 100644 index 00000000..ba8f142f --- /dev/null +++ b/archive/retroarch-enduserguide.lyx @@ -0,0 +1,2792 @@ +#LyX 2.0 created this file. For more info see http://www.lyx.org/ +\lyxformat 413 +\begin_document +\begin_header +\textclass article +\use_default_options true +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding auto +\fontencoding global +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 + +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\spacing single +\use_hyperref true +\pdf_title "RetroArch End-user Guide" +\pdf_bookmarks true +\pdf_bookmarksnumbered false +\pdf_bookmarksopen false +\pdf_bookmarksopenlevel 1 +\pdf_breaklinks false +\pdf_pdfborder false +\pdf_colorlinks true +\pdf_backref false +\pdf_pdfusetitle true +\papersize default +\use_geometry false +\use_amsmath 1 +\use_esint 1 +\use_mhchem 1 +\use_mathdots 1 +\cite_engine basic +\use_bibtopic false +\use_indices false +\paperorientation portrait +\suppress_date false +\use_refstyle 1 +\index Index +\shortcut idx +\color #008000 +\end_index +\secnumdepth 5 +\tocdepth 5 +\paragraph_separation indent +\paragraph_indentation default +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Title +RetroArch End-User Guide +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part* +Welcome to RetroArch! +\end_layout + +\begin_layout Standard +RetroArch does things differently from other programs. + In this guide, you will learn what RetroArch is, how it works and the various + things you can do with it as an end-user. +\end_layout + +\begin_layout Standard +This guide is aimed at the end-user. + It does not intend to be a comprehensive reference for anything and everything + to do with the libretro project and/or RetroArch. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset CommandInset toc +LatexCommand tableofcontents + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +What is RetroArch? +\end_layout + +\begin_layout Standard +RetroArch is a cross platform architecture that aims to become a 'one-stop + shop' for emulators, videogames, multimedia, augmented reality and other + areas of interest. + It manages to do all of these things by implementing a specification known + as the libretro API (Application Programming Interface). +\end_layout + +\begin_layout Standard +Libretro is a powerful interface that allows you to port applications to + the spec and be able to run them on any libretro-compatible client in existence. +\end_layout + +\begin_layout Standard +RetroArch is the 'official' libretro client. + Right now it is available on many platforms and it aims to deliver the + most optimal performance possible on a given host platform. + You will generally find that RetroArch will be first in implementing new + features and/or additions that get added to the libretro interface. +\end_layout + +\begin_layout Standard +RetroArch is most well known for an entire suite of emulators that have + been ported to the libretro specification and are therefore able to be + run in RetroArch. + Therefore, it has been compared in the media to other multi-system emulators, + such as OpenEmu, and/or MESS. + Note that we don't particularly approve of this attempt to pigeonhole RetroArch + - we don't think of libretro and/or RetroArch as being limited to emulators, + or even games for that matter. +\end_layout + +\begin_layout Standard +Over the next few months the distinction between RetroArch and these types + of programs will start becoming more and more apparent. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +What platforms can I use RetroArch on? +\end_layout + +\begin_layout Standard +Being on every system anywhere is the most important goal of RetroArch. + Therefore, it is available for many platforms - for free. + The program (except for minor cosmetic differences per version) should + behave more or less exactly the same from one platform to another. +\end_layout + +\begin_layout Standard +The list of available devices and/or operating systems include: +\end_layout + +\begin_layout Itemize +PC (Microsoft Windows XP/Vista/7/8/8.1) +\end_layout + +\begin_layout Itemize +Mac (OSX Snow Leopard [10.6.8] up to Mavericks [10.9]) +\end_layout + +\begin_layout Itemize +Linux +\end_layout + +\begin_layout Itemize +Android (version 2.3 and higher) +\end_layout + +\begin_layout Itemize +iOS (version 6.0 and higher [*]) +\end_layout + +\begin_layout Itemize +Blackberry Playbook +\end_layout + +\begin_layout Itemize +Blackberry 10 +\end_layout + +\begin_layout Itemize +PlayStation3 [*] +\end_layout + +\begin_layout Itemize +Nintendo Wii [*] +\end_layout + +\begin_layout Itemize +Nintendo GameCube [*] +\end_layout + +\begin_layout Itemize +Microsoft Xbox [*] +\end_layout + +\begin_layout Itemize +Microsoft Xbox 360 [*] +\end_layout + +\begin_layout Itemize +Browser / Javascript (Emscripten) +\end_layout + +\begin_layout Standard +Some of the systems listed above (the ones marked [*]) might require a jailbreak + or a modification of some sort so that RetroArch is able to run on it. + This is something you will have to figure out on your own and for which + we provide no support or help at all. +\end_layout + +\begin_layout Standard +For the latest versions, go to the official homepage - +\begin_inset Flex URL +status open + +\begin_layout Plain Layout + +http://www.libretro.com +\end_layout + +\end_inset + +, and click on the platform you want to download a copy of RetroArch for. +\end_layout + +\begin_layout Standard +In the future, RetroArch will be ported to even more systems. + The aim for RetroArch is to have a program that will be able to run on + as many platforms as possible, and bringing along with it all the libretro + cores that RetroArch (as a libretro client) is able to run. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +How does RetroArch work? +\end_layout + +\begin_layout Standard +RetroArch is a plugin-driven application. + Every program that you can run in RetroArch is a plugin that gets loaded + by RetroArch on-the-fly. + We refer to these plugin cores from this point on as 'libretro cores'. +\end_layout + +\begin_layout Standard +A libretro core is an app implementing the libretro specification packaged + as a plugin. + The 'libretro core' defines the 'behavior' of what RetroArch will do, since + RetroArch by itself does nothing. + So, a core can turn RetroArch into a videogame emulator, a game, a movie + player, etc. + It's up to what the developer wants the libretro core to do. +\end_layout + +\begin_layout Standard +Through this model, apps implementing the libretro specification form part + of a larger ecosystem that every libretro-compatible client will be able + to tap into. + Libretro's aim is to make convergence possible - so that you can run an + app on one system, then run it on another system, or play in a browser + and then continue and pick up where you left off by launching the same + app from your mediaplayer. +\end_layout + +\begin_layout Standard +RetroArch can be thought of as the 'Proof of Concept' that demonstrates + that this kind of convergence is possible. + Other apps (media players, multi-system emus, CAD applications) are encouraged + and allowed to implement the specification themselves. + +\end_layout + +\begin_layout Standard +The user can do many things with RetroArch, from playing games to watching + movies (and other activities in the near future). + The user is in control of what he wants to turn RetroArch into, for what + purposes it will be used and what content will be run in it. + There is no digital rights management or restrictions imposed upon the + user. + +\end_layout + +\begin_layout Standard +A brief summary of all available 'libretro cores' so far will be provided + at the end of this guide. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +How do you control RetroArch? +\end_layout + +\begin_layout Standard +RetroArch (and libretro as a result) has been designed around one common + input device - something we call the 'RetroPad'. + You use this input device for controlling all aspects of RetroArch - from + the game to the RetroArch system menus. +\end_layout + +\begin_layout Standard +The RetroPad is a traditional videogame controller of the Nintendo/Sony + mould. + It has a D-pad, a Start/Select button, four face buttons, up to 4 shoulder + buttons/triggers, and (optional) two analog sticks. +\end_layout + +\begin_layout Standard +Unlike other apps, RetroArch is designed to be controlled with a gamepad + as its primary input. + We want to deliver a user experience that is as close to a traditional + videogame console as possible, and to that end, we believe having to jockey + between a keyboard, a mouse, and/or a gamepad/mouse is a bad user experience + - when you could all do it with your gamepad anyway. +\end_layout + +\begin_layout Standard +The RetroPad is an 'abstraction' - when you run RetroArch, your own gamepad + (or keyboard/touch overlay) will have a 1-to-1 mapping to this 'RetroPad' + abstraction. + You map your input device of choice to all the buttons and triggers that + the RetroPad supports, and from there on you can control RetroArch's built-in + menu system +\begin_inset Foot +status collapsed + +\begin_layout Plain Layout +On tablets and phones, you can interact with the upper-layer system menus + through touch +\end_layout + +\end_inset + +. +\end_layout + +\begin_layout Standard +The mobile ports (because of touch being the primary input device) are controlle +d using a graphical overlay of the RetroPad that gets pasted on top of the + screen. + This overlay can be interacted with through touch, and it's possible to + switch between different 'pages' of the overlay - and to switch overlays + on-the-fly. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +How do I go to the built-in UI? +\end_layout + +\begin_layout Standard +RetroArch has a built-in UI (User Interface) that functions nearly the same + across every platform. + It is called RGUI (short for Retro GUI). + Most of RetroArch's features can be changed on-the-fly from this. + +\end_layout + +\begin_layout Standard +Just like everything else in RetroArch, RGUI is controlled with the RetroPad. + Like the name suggests, it is a no-frills User Interface that is not big + on eye-candy. + On the plus side, it is very scaleable and works well even at resolutions + as low as 320x240. + +\end_layout + +\begin_layout Standard +The user has two ways to bring up this menu: +\end_layout + +\begin_layout Itemize +Button bind - most RetroArch versions allow you to bind 'Toggle Menu' to + a key/button on your input device. + By pressing this button/key, you can toggle the built-in UI on or off. +\end_layout + +\begin_layout Itemize +Overlay - An overlay usually contains a button with a 'space invaders' icon + in it. + Touching this button will toggle the built-in UI on or off. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +How do I load content in RetroArch? +\end_layout + +\begin_layout Standard +A version of RetroArch typically has three ways to load content. + You can select these options from the built-in UI. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Load Content (History):} +\end_layout + +\end_inset + +You can select from a list of previously loaded content here. + All the content you have ran in RetroArch will be added to this list. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Load Content (Detect Core):} +\end_layout + +\end_inset + +You can select a file from the filebrowser. + It will try to detect if a core has been installed that supports the extension + of the file you just selected. + If it finds only one core that supports this file extension, it will autostart + that core with the chosen content immediately. + If it finds multiple cores that supports this file extension,it will let + you choose from a list of supported cores. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Load Content:} +\end_layout + +\end_inset + +You can select a file from the filebrowser, and it will be started with + the currently selected 'core'. + In order to change the core currently being selected, you have to select + another one from 'Load Core'. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Part +Listing of available cores +\end_layout + +\begin_layout Standard +The number of plugin cores that get added to the libretro ecosystem keeps + increasing. + Covering all of these would fall outside the scope of this guide, so we're + only going to cover a few ones in more detail. +\end_layout + +\begin_layout Standard +We try to make an effort to have a core run on as many systems as possible. + Unfortunately, there will always be instances where a core is not available + for a specific platform. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +bsnes +\end_layout + +\begin_layout Standard +This is a Super Nintendo emulator based on the open-source emulator bsnes. + It is an accuracy-focused emulator and as such can run almost all games + for the SNES with cycle accuracy, unlike other SNES emulators. + However, this comes at the cost of performance. +\end_layout + +\begin_layout Subsection +How to run +\end_layout + +\begin_layout Standard +bSNES does not work on its own, but runs SNES ROM images. + These image files need to have the following extensions +\end_layout + +\begin_layout Itemize +sfc +\end_layout + +\begin_layout Standard +Select one of these. + If the image is verified to be OK, it will start up the game. +\end_layout + +\begin_layout Subsection +How do all these different versions compare? +\end_layout + +\begin_layout Standard +There are several versions of bsnes out there. +\end_layout + +\begin_layout Subsubsection +bsnes Performance v0.92 +\end_layout + +\begin_layout Standard +This is a fairly recent version of bsnes' performance core - the same one + used in Higan. + Some games - like Mega Man X2 and X3 - are broken with this version even + if you have the BIOS files placed in your System directory. + Some of the games requiring high accuracy won't run correctly either. + To make up for it, it has much better performance than the balanced or + accuracy cores. +\end_layout + +\begin_layout Subsubsection +bsnes Balanced v0.92 +\end_layout + +\begin_layout Standard +This is a fairly recent version of bsnes' performance core - the same one + used in Higan. + It should play games like Mega Man X2/X3 with no problems. + It is much slower than bsnes performance but still a lot faster than bsnes + accuracy. +\end_layout + +\begin_layout Subsubsection +bsnes Accuracy v0.92 +\end_layout + +\begin_layout Standard +This is a fairly recent version of bsnes' accuracy core - the same one used + in Higan. + This should be capable of playing all SNES games accurately at the cost + of performance. +\end_layout + +\begin_layout Subsubsection +bsnes Performance C++98 v0.85 +\end_layout + +\begin_layout Standard +Later versions of bsnes are written in cutting-edge C++11 and cannot be + used on certain outdated compilers. + This port of bsnes to C++98 was written for those compilers in mind. + It is an older version of bsnes compared to the one in Higan but there + should only be minor differences between this and bsnes performance v0.92. + +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Cartridge folders not enforced +\end_layout + +\begin_layout Standard +Cartridge folders are not forced on you, and you are still able to load + SFC ROMs without having to go the Purify route. +\end_layout + +\begin_layout Subsubsection +More pragmatic static syncing +\end_layout + +\begin_layout Standard +Higan's way of static synchronization is for all intents and purposes like + RetroArch's, except ours is superior from an end-user point of view. + It does not require of the user that he has to dial a figurative knob for + hours on end to get the 'perfect refresh rate' of his monitor as a reference + clock for the emulator - instead, it only requires that the app refresh + rate you use is close enough to the refresh rate of your screen. + From there on, dynamic rate control picks up the slack for whenever audio + is running late, and combined with threaded video this allows highly demanding + and sync-heavy cores like bsnes to run tolerably even on a very high-latency + OS like Android. +\end_layout + +\begin_layout Subsection +Known issues +\end_layout + +\begin_layout Subsubsection +Mega Man X2/X3 don't run with bsnes performance core +\end_layout + +\begin_layout Standard +This is a known issue and it's unlikely byuu is going to fix it for the + performance core. + You will have to use either Balanced or Accuracy core. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Dinothawr +\end_layout + +\begin_layout Standard +Dinothawr is an indie game made by one of RetroArch's lead authors. + It is a simple block puzzler that is similar in gameplay to Sokoban and + Kickle Kubicle. + It is the first game that is designed from the ground up as a core for + RetroArch. + The standalone version of this game has a cutdown version of RetroArch + included as an integral part of the app. +\end_layout + +\begin_layout Subsection +How to run +\end_layout + +\begin_layout Enumerate +Go to this website - +\begin_inset Flex URL +status open + +\begin_layout Plain Layout + +https://github.com/libretro/Dinothawr +\end_layout + +\end_inset + + and select 'Download to ZIP'. +\end_layout + +\begin_layout Enumerate +Extract the ZIP file on your device. +\end_layout + +\begin_layout Enumerate +Start up RetroArch. + Select 'Load Content' (either 'Load Content (Detect Core)' or plain 'Load + Content' will do). +\end_layout + +\begin_layout Enumerate +Go to the directory where you extracted the contents of the ZIP file to + (see step 2). +\end_layout + +\begin_layout Enumerate +Select 'dinothawr.game'. + The game should now start up. +\end_layout + +\begin_layout Subsection +Controls +\end_layout + +\begin_layout Subsubsection +RetroPad default mapping +\end_layout + +\begin_layout Standard +These are the default button mappings on the RetroPad. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{B BUTTON} +\end_layout + +\end_inset + + - Push block +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{A BUTTON} +\end_layout + +\end_inset + + - Go back to previous menu +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{D-PAD} +\end_layout + +\end_inset + + - Movement +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +MAME 2003 +\end_layout + +\begin_layout Standard +This is a multi-system arcade emulator based on a late 2003 version of MAME + (to be specific, it's version 0.78). + This old ancient version has been picked because MAME has gotten drastically + slower over the years, and a version dating back to 2003 would still be + fast enough for running most games on previous-generation videogame consoles + and mobile. +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Midway DCS speed hacks re-addition +\end_layout + +\begin_layout Standard +After version 0.72, MAMEdev removed various speedhacks for games using Midway + DCS which led to these games being rendered more or less unplayable on + current-day hardware (by 2003 standards) back then. + These speedhacks have been re-integrated into the MAME 0.78 codebase, and + they are of great benefit to the runtime performance of games like Mortal + Kombat 1/2/3/Ultimate, NBA Jam and other Midway games using this hardware. +\end_layout + +\begin_layout Subsection +Notes +\end_layout + +\begin_layout Itemize +You can bring up MAME's OSD GUI by pressing the R2 button on the RetroPad. +\end_layout + +\begin_layout Itemize +MAME 2014 supports the RetroKeyboard as an input device as well. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +MAME 2010 +\end_layout + +\begin_layout Standard +This is a multi-system arcade emulator based on a late 2010 version of MAME + (to be specific, it's version 0.139). + This makes it competitive with MAME4Droid Reloaded which also targets this + codebase. + This halfway house between MAME 2003 and MAME 2014 is mainly intended for + more powerful mobile platforms that were released during 2012 to 2013. + While far slower than MAME 2003, it is still measurably faster than MAME + 2014. +\end_layout + +\begin_layout Standard +Compared to MAME 2003, MAME 2010 has a lot more content available. + For instance, Namco System 11/12 games can be played with full sound, Capcom + CPS3 support was added, Killer Instinct 1/2 are fully playable, Dynamic + recompilation support for 64bit got added, and more. +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Cave SH3 re-addition +\end_layout + +\begin_layout Standard +The Cave SH3 drivers were removed at a specific point in time due to a legal + dispute between Cave and MAMEdev. + This driver has been readded to MAME 2010. +\end_layout + +\begin_layout Subsection +Notes +\end_layout + +\begin_layout Itemize +You can bring up MAME's OSD GUI by pressing the R2 button on the RetroPad. +\end_layout + +\begin_layout Itemize +MAME 2014 supports the RetroKeyboard as an input device as well. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +MAME 2014 +\end_layout + +\begin_layout Standard +This is a multi-system arcade emulator based on the latest version of MAME + (as of this moment, 0.151). + Far slower than MAME 2003 and measurably slower than MAME 2010, it makes + up for this with increased game compatibility and feature completeness. +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Cave SH3 re-addition +\end_layout + +\begin_layout Standard +The Cave SH3 drivers were removed at a specific point in time due to a legal + dispute between Cave and MAMEdev. + This driver has been readded to MAME 2014. + It will probably be readded soon to MAME mainline as well. +\end_layout + +\begin_layout Subsection +Notes +\end_layout + +\begin_layout Itemize +You can bring up MAME's OSD GUI by pressing the R2 button on the RetroPad. +\end_layout + +\begin_layout Itemize +MAME 2014 supports the RetroKeyboard as an input device as well. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Mupen64 Plus +\end_layout + +\begin_layout Standard +This is a Nintendo 64 emulator based on the open-source emulator Mupen64 + Plus. + It is a current work-in-progress that aims primarily at the PC and mobile + platforms, such as Android, iOS, Blackberry, and others. + It ships with three graphics plugins - of which Glide64 has been worked + on the most and is the most accurate, but also the slowest. + Development on the other two plugins will take more work. +\end_layout + +\begin_layout Subsection +How to run +\end_layout + +\begin_layout Standard +Mupen64 Plus does not work on its own, but runs N64 ROM images. + These image files need to have one of the following extensions: +\end_layout + +\begin_layout Itemize +n64 +\end_layout + +\begin_layout Itemize +v64 +\end_layout + +\begin_layout Itemize +z64 +\end_layout + +\begin_layout Standard +Select one of these. + If the image is verified to be OK, it will start up the game. +\end_layout + +\begin_layout Subsection +Controls +\end_layout + +\begin_layout Subsubsection +RetroPad default mapping +\end_layout + +\begin_layout Standard +These are the default button mappings on the RetroPad. + It is assumed that your RetroPad has two analog sticks so that the N64's + analog stick and the C buttons can be mapped to them. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{B BUTTON} +\end_layout + +\end_inset + + - (Normal press) N64 B button / (Press and hold with R2) C Button Down +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{A BUTTON} +\end_layout + +\end_inset + + - (Normal press) N64 A button / (Press and hold with R2) C Button Right +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Y BUTTON} +\end_layout + +\end_inset + + - (Press and hold with R2) C Button Left +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{X BUTTON} +\end_layout + +\end_inset + + - (Press and hold with R2) C Button Up +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L BUTTON} +\end_layout + +\end_inset + + - N64 L Trigger +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R BUTTON} +\end_layout + +\end_inset + + - N64 R Trigger +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L2 BUTTON} +\end_layout + +\end_inset + + - N64 Z Trigger +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R2 BUTTON} +\end_layout + +\end_inset + + - (Modifier button) - press and hold this plus one of the face buttons + to do C button presses +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{D-PAD} +\end_layout + +\end_inset + + - N64 D-Pad +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{SELECT} +\end_layout + +\end_inset + + - Toggle between per-game control layouts +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{START} +\end_layout + +\end_inset + + - N64 Start button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{LEFT STICK} +\end_layout + +\end_inset + + - N64 Analog stick +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{RIGHT STICK} +\end_layout + +\end_inset + + - N64 C buttons mapped to stick like the Gamecube's C Stick +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Plug-and-play configuration of games +\end_layout + +\begin_layout Standard +N64 emulators are traditionally dependent on numerous config/database files + that the user has to manually update from time to time. + These database files contain core-specific settings needed to play the + game correctly (or at all). + This varies from Save Type to which Glide 64 settings should be enabled + to get the game to look correctly. +\end_layout + +\begin_layout Standard +This libretro port tries to automate as much of that stuff as possible and + integrate it into the core. + No longer will you need to have a Mupen64plus.ini and an RDB database from + which all this information will get pulled. +\end_layout + +\begin_layout Standard +The Glide64 config file which was previously a necessity has also been totally + integrated into the core - to the extent that even the microcode mappings + for each game are included. + So that config file is not needed any longer either. +\end_layout + +\begin_layout Standard +Baking in the config files for glN64 and Rice will take some more time. + These have not been included as of yet. +\end_layout + +\begin_layout Subsubsection +60fps framerates in nearly all games with specific core settings +\end_layout + +\begin_layout Standard +There have been other N64 emulator forks that have advertised being able + to run games like GoldenEye 007 at 60fps. + Our approach is most like Project64's in which VI Rate gets increased from + the default (1500) to 2200. +\end_layout + +\begin_layout Standard +Some games are framerate throttled so they can't ever reach 60fps - however, + even these games will benefit from setting VI Refresh to 2200 and Framerate + to 'fullspeed'. + You will notice that a lot of input latency and slowdown will be removed + under these settings. +\end_layout + +\begin_layout Subsubsection +Targets OpenGL - both desktop and GLES +\end_layout + +\begin_layout Standard +We are using the GLES2 branches of Glide64, Rice and glN64. + The libretro port of Mupen64plus targets OpenGL instead of spreading itself + thin between Direct3D and OpenGL. + We try to make sure that the code works for both desktop GL and GLES at + the same time. +\end_layout + +\begin_layout Standard +We have also made a lot of optimizations/changes to these rasterizer codebases + so that they perform better on our target platforms. + We are not anyway near done with that though. +\end_layout + +\begin_layout Subsubsection +Accuracy settings +\end_layout + +\begin_layout Standard +Turning on all the knobs in a demanding graphics plugin like Glide64 can + lead to almost glitchless graphics, but it comes at a heavy performance + cost. + For this reason, 'accuracy' settings per graphics plugins are introduced + as core options. + If you care more about double the framerate instead of the current framebuffer + image being displayed on a wall billboard in Mario Kart 64, then you can + set the Accuracy slider to a less high setting, and vice versa. +\end_layout + +\begin_layout Subsubsection +Incorporates low-level RSP next to High-Level RSP - cxd4 +\end_layout + +\begin_layout Standard +Certain games will have certain sound effects missing with the default high-leve +l RSP plugin, such as GoldenEye 007. + Others will simply sound wrong, such as PilotWings 64. + The low-level RSP accurately emulates these effects at a signficant performance + cost. +\end_layout + +\begin_layout Standard +The plugin also handles certain graphics functions that the high-level RSP + is missing. + For instance, Resident Evil 2 requires that you use the low-level RSP plugin + in order for all the FMV movies and backgrounds to work. +\end_layout + +\begin_layout Subsubsection +Preconfigured 'sane' controls for various targeted games +\end_layout + +\begin_layout Standard +The N64 controller was not always the best pad for certain games, and having + to map them to the RetroPad clearly makes that very apparent. + We have remapped the controls in various games so that you can get a more + pleasant gameplay experience. + If you don't like this 'sanitized' control scheme, you can switch on-the-fly + between it and the default control scheme by pressing Select (a button + which was absent on the N64 pad - which is convenient for us since it gives + us an extra button on our RetroPad to do 'stuff' with). +\end_layout + +\begin_layout Standard +A couple of examples - Killer Instinct Gold is now mapped like the SNES + Killer Instinct, Wipeout 64 is mapped like the PS1 Wipeout 2097, Mortal + Kombat Trilogy is mapped like Mortal Kombat on the SNES and PS1, Resident + Evil 2 is mapped like the PS1 version, and so on. + Since the RetroPad is a replica of the Dual Shock, remapping controls this + way just makes a lot more sense. + And if you don't want it, you can disable it anyway and/or remap to your + heart's content. +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Known resolvable issues +\end_layout + +\begin_layout Subsubsection +Conker BFD and Perfect Dark crash with the low-level RSP plugin +\end_layout + +\begin_layout Standard +Don't use the low-level RSP plugin with these games. + Instead, use the high-level RSP plugin. +\end_layout + +\begin_layout Subsubsection +Resident Evil 2 doesn't work correctly with the high-level RSP plugin +\end_layout + +\begin_layout Standard +You need to use the low-level RSP plugin for this game to work correctly. +\end_layout + +\begin_layout Subsubsection +I can't use the Rice plugin +\end_layout + +\begin_layout Standard +Make sure that a config file called RiceVideoLinux.ini has been placed in + your 'system' directory. + The libretro Mupen64plus core still depends on this file being there in + order to execute the Rice plugin. +\end_layout + +\begin_layout Subsection +Known issues +\end_layout + +\begin_layout Standard +Consider the Mupen64 core right now at an advanced alpha state. + Lots of issues are known about and will be looked at. + The most prominent ones we are aware of are listed below. +\end_layout + +\begin_layout Subsubsection +iOS dynamic recompiler bugs +\end_layout + +\begin_layout Standard +Right now the dynamic recompiler for iOS is not at parity with Android. + This means that certain games might either crash or freeze at certain points + due to bugs still lurking in the code. + One example of this is GoldenEye 007 crashing at startup. + We are working hard on resolving these remaining issues so that the iOS + port is at least equal to the Android port. +\end_layout + +\begin_layout Subsubsection +Wobbling textures with Glide64 in certain games +\end_layout + +\begin_layout Standard +Ground texture wobbling seems to occur in games like Super Mario 64, Star + Fox 64, F-Zero X and other games depending on how close the camera is to + the ground. + This seems to be an issue with Glide64 in general. + We will try to investigate this issue. +\end_layout + +\begin_layout Subsubsection +GoldenEye 007 - Glide64 - frigate level - water surface disappearing vertices +\end_layout + +\begin_layout Standard +You will be able to notice significant polygon breakup when first entering + this stage on the boat. + Vertices of the water surface appear black depending on the proximity of + the camera to the surface. + This, like 3.3.2, seems to be also an issue with Glide64 that we will have + to investigate. +\end_layout + +\begin_layout Subsubsection +Broken framebuffer effects in glN64 +\end_layout + +\begin_layout Standard +This is a known issue and it will probably be trivial to hook this up. +\end_layout + +\begin_layout Subsubsection +Other glN64/Rice issues +\end_layout + +\begin_layout Standard +Most of the hard work has gone into Glide64 at this point so the glN64/Rice + side has not been actively worked on - though we intend to do so eventually. +\end_layout + +\begin_layout Subsubsection +Tsumi to Batsu (Sin and Punishment) crashes either at startup or at exit +\end_layout + +\begin_layout Standard +Known issue and currently no fix for it. + Will have to be debugged. +\end_layout + +\begin_layout Subsubsection +Star Wars: Shadows of the Empire sometimes boots, sometimes crashes +\end_layout + +\begin_layout Standard +This is a known issue, and there is currently no fix for it. +\end_layout + +\begin_layout Subsubsection +Pokemon Puzzle League doesn't work +\end_layout + +\begin_layout Standard +This is a known issueand there is currently no fix for it. +\end_layout + +\begin_layout Subsubsection +Blast Corps - Crashes after Rare logo with dynarec on ARM devices +\end_layout + +\begin_layout Standard +This is a known issue. + The very same issue happens with Mupen64 Plus AE too. + Currently, the only way to play this game on an ARM device would be to + switch the CPU core to 'Cached interpreter'. + This will however make the game run way too slow (possible exception being + Apple A7 CPUs and competing hardware). +\end_layout + +\begin_layout Subsubsection +Perfect Dark is very slow in scenes with framebuffer effects or motion blur +\end_layout + +\begin_layout Standard +This is a known issue. + The issue is that the only way to accelerate these scenes would be to use + Hardware Framebuffer Emulation, and that has drawbacks of its own such + as vertices with black textures after certain scenes have ran (such as + the Spycam). + For now there is no good fix for this other than doing it all on the CPU, + which is CPU-intensive and slow. +\end_layout + +\begin_layout Subsubsection +Conker's BFD - Conker has no shadow +\end_layout + +\begin_layout Standard +This is a known issue. + Shadows depend on a depth texture being rendered, and the only way to render + these is to use Hardware Framebuffer Emulation. + While we can enable this mode, it has severe drawbacks in other areas right + now that precludes its use. + Therefore, currently the shadow is stubbed out. +\end_layout + +\begin_layout Subsubsection +PilotWings 64 - There is a very annoying long black vertice obscuring a + great part of the screen +\end_layout + +\begin_layout Standard +This is a known issue, and it seems to happen with glN64 too and mainline + Mupen64 in general. + What is supposed to happen there is that a shadow on the ground should + be in place of these broken vertice spans. + A fix is not yet known. + There is a 'duct-tape hack' core setting that makes this 'glitch' somewhat + more bearable - it makes the culled vertice appear translucent instead + of solid - which means you can watch through it. +\end_layout + +\begin_layout Subsubsection +Legend of Zelda: Majora's Mask - subscreen framebuffer image takes about + five seconds to appear +\end_layout + +\begin_layout Standard +This is a known issue, and a fix is not yet known. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +NX Engine +\end_layout + +\begin_layout Standard +This is a game engine capable of running the game +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Cave Story} +\end_layout + +\end_inset + + (Japanese title: +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Doukutsu Monogatari} +\end_layout + +\end_inset + +). + It is based on an open-source game engine recreation called NX Engine. + An extensive code rewrite has been done for the purposes of increased portabili +ty and performance. +\end_layout + +\begin_layout Subsection +How to run +\end_layout + +\begin_layout Standard +In order to run the game, you need to have the original datafiles from the + original freeware PC version. +\end_layout + +\begin_layout Enumerate +Go to this website - +\begin_inset Flex URL +status open + +\begin_layout Plain Layout + +https://github.com/libretro/nxengine-libretro +\end_layout + +\end_inset + + and select 'Download to ZIP'. +\end_layout + +\begin_layout Enumerate +Extract the ZIP file on your device. +\end_layout + +\begin_layout Enumerate +Start up RetroArch. + Select 'Load Content' (either 'Load Content (Detect Core)' or plain 'Load + Content' will do). +\end_layout + +\begin_layout Enumerate +Go to the directory where you extracted the contents of the ZIP file to + (see step 2). + Select the directory 'datafiles'. +\end_layout + +\begin_layout Enumerate +Select 'Doukutsu.exe'. + The game should now start up. +\end_layout + +\begin_layout Subsection +Controls +\end_layout + +\begin_layout Subsubsection +RetroPad default mapping +\end_layout + +\begin_layout Standard +These are the default button mappings on the RetroPad. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{B BUTTON} +\end_layout + +\end_inset + + - Jump +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Y BUTTON} +\end_layout + +\end_inset + + - Shoot +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{X BUTTON} +\end_layout + +\end_inset + + - Map screen +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L BUTTON} +\end_layout + +\end_inset + + - Weapon cycle left +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R BUTTON} +\end_layout + +\end_inset + + - Weapon cycle right +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{D-PAD} +\end_layout + +\end_inset + + - Movement +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{SELECT} +\end_layout + +\end_inset + + - Options screen +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{START} +\end_layout + +\end_inset + + - Inventory screen +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Caches all assets - avoids disk I/O overhead +\end_layout + +\begin_layout Standard +The original NXEngine source was quite inefficiently written and had very + high disk I/O overhead. + This all but killed performance on the game consoles where disk I/O is + very slow. + What happens instead now is that instead of dumping all content from the + main binary to disk, it caches it in memory so that there is zero overhead + from accessing assets. + This way, NXEngine is playable at fullspeed on any system without any disk + I/O spikes - including consoles. +\end_layout + +\begin_layout Subsubsection +Ability to switch between 50fps (default) and 60fps +\end_layout + +\begin_layout Standard +The original game ran at 50 frames per second. + For the libretro port, we have made an optional toggle so you can switch + the game to 60 frames per second. + You can do this by pressing the Select button to go to the Options screen, + and changing 'FPS' from 50 to 60, and vice versa. +\end_layout + +\begin_layout Section +PCSX ReARMed +\end_layout + +\begin_layout Standard +This is a Sony PlayStation 1 emulator based on the open-source emulator + PCSX Reloaded. + It has been specifically optimized for mobile platforms, such as Android, + iOS and Pandora. + It also has a software-rendered graphics renderer, called NEON GPU plugin, + that is more accurate than most PlayStation 1 emulators. +\end_layout + +\begin_layout Subsection +How to run +\end_layout + +\begin_layout Standard +PCSX ReARMed does not work on its own, but runs PlayStation1 CD images. + These image files need to have one of the following extensions: +\end_layout + +\begin_layout Itemize +bin +\end_layout + +\begin_layout Itemize +cue +\end_layout + +\begin_layout Itemize +img +\end_layout + +\begin_layout Itemize +mdf +\end_layout + +\begin_layout Itemize +pbp +\end_layout + +\begin_layout Itemize +toc +\end_layout + +\begin_layout Itemize +cbn +\end_layout + +\begin_layout Itemize +m3u +\end_layout + +\begin_layout Standard +Select one of these. + If the image is verified to be OK,it will start up the game. +\end_layout + +\begin_layout Subsection +Controls +\end_layout + +\begin_layout Subsubsection +RetroPad default mapping +\end_layout + +\begin_layout Standard +These are the default button mappings on the RetroPad. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{B BUTTON} +\end_layout + +\end_inset + + - PS1 X button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{A BUTTON} +\end_layout + +\end_inset + + - PS1 Circle button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Y BUTTON} +\end_layout + +\end_inset + + - PS1 Square button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{X BUTTON} +\end_layout + +\end_inset + + - PS1 Triangle button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L BUTTON} +\end_layout + +\end_inset + + - PS1 L1 Button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R BUTTON} +\end_layout + +\end_inset + + - PS1 R1 Button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L2 BUTTON} +\end_layout + +\end_inset + + - PS1 L2 Button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R2 BUTTON} +\end_layout + +\end_inset + + - PS1 R2 Button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{D-PAD} +\end_layout + +\end_inset + + - PS1 D-Pad +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{SELECT} +\end_layout + +\end_inset + + - PS1 Select button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{START} +\end_layout + +\end_inset + + - PS1 Start button +\end_layout + +\begin_layout Subsubsection +RetroPad DualShock controls +\end_layout + +\begin_layout Standard +To enable this mode, you need to go to Core Options and set 'Pad 1 Type' + to 'analog'. + Your RetroPad is assumed to have two analog sticks to be able to use this + mode. + Note that not all games might work in DualShock mode, and vice versa - + so switch between them if the controls don't work. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{LEFT STICK} +\end_layout + +\end_inset + + - PS1 Left Analog Stick +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{RIGHT STICK} +\end_layout + +\end_inset + + - PS1 Right Analog Stick +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L3} +\end_layout + +\end_inset + + - PS1 L3 Button +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R3} +\end_layout + +\end_inset + + - PS1 R3 Button +\end_layout + +\begin_layout Subsection +Setting up BIOS files +\end_layout + +\begin_layout Standard +The compatibility of PCSX ReARMed is increased a lot by using real BIOS + firmware images. + +\end_layout + +\begin_layout Standard +PCSX ReARMed looks for the following BIOS files: +\end_layout + +\begin_layout Itemize +scph1001.bin +\end_layout + +\begin_layout Itemize +scph5501.bin +\end_layout + +\begin_layout Itemize +scph7001.bin +\end_layout + +\begin_layout Standard +These files should be placed inside your System directory. + If your system directory path does not point to anything, it will try to + load the BIOS files from the same directory as the CD image. +\end_layout + +\begin_layout Subsection +Core options +\end_layout + +\begin_layout Subsubsection +Increasing graphics resolution +\end_layout + +\begin_layout Standard +You can increase the internal graphics resolution by enabling the core option + 'Enable NEON enhanced resolution (slow)' This will force the core to render + at a resolution of 1024x512 +\begin_inset Foot +status collapsed + +\begin_layout Plain Layout +This mode is deactivated on games that have high-resolution interlaced graphics + modes, such as Tekken 3 and Tobal 2. + Setting this option to 'ON' or 'OFF' will make no change. +\end_layout + +\end_inset + +. + This will significantly increase the quality of the graphics, but it will + also impact performance. + Only enable this option if you are on a fast platform with enough CPU power + - otherwise you're best off leaving this core option 'off'. +\end_layout + +\begin_layout Subsubsection +Disabling interlacing for better performance with interlaced games +\end_layout + +\begin_layout Standard +High-resolution interlaced games such as Tekken 3 and Tobal 2 would typically + be displayed in interlaced mode on a real PlayStation. + The emulator typically renders these games with interlacing turned off. + This however will have an impact on performance. + If you find that your platform for whatever reason is falling below fullspeed, + it can help to set the core option 'Interlacing' to 'ON'. +\end_layout + +\begin_layout Subsubsection +Disabling dynarec for platforms that don't support JIT compilation (Windows + Phone/RT, non-jailbroken iOS) +\end_layout + +\begin_layout Standard +Normally, PCSX ReARMed starts up with the dynarec CPU core being automatically + activated. +\end_layout + +\begin_layout Standard +There are some platforms that don't allow for JIT compilation inside an + app (which is what the dynarec CPU core relies upon). + These include: +\end_layout + +\begin_layout Itemize +Non-jailbroken iOS +\end_layout + +\begin_layout Itemize +Windows RT +\end_layout + +\begin_layout Itemize +Windows Phone +\end_layout + +\begin_layout Standard +You will need to disable the core option 'Dynarec' if you want to be able + to run this core on such a device. + Be aware that disabling the dynarec is very CPU-intensive and might result + in PCSX ReARMed not being able to run fullspeed on yur device. + Disable dynarec therefore only if you absolutely must. +\end_layout + +\begin_layout Subsection +Known outstanding issues +\end_layout + +\begin_layout Subsubsection +Garbled sound samples at times +\end_layout + +\begin_layout Standard +Sound emulation is not perfect. + At some point we intend to backport the latest sound driver from PCSX Reloaded + and offer a way to toggle between the original driver and the latest PCSXR + one. + The original PCSX ReARMed version was geared around the Pandora, which + is limited by a 1Ghz Cortex A8 CPU - concessions had to be made. + Today's mobile devices are far more powerful than this and should be capable + of much more demanding sound emulation. +\end_layout + +\begin_layout Subsubsection +Broken geometry in Jumping Flash 1/2 +\end_layout + +\begin_layout Standard +This is caused by an inaccurate Geometry Transfer Engine plugin used in + PCSX ReARMed. + A core option will probably have to be included at some point that allows + the user to switch between inaccurate/fast GTE and accurate GTE emulation. +\end_layout + +\begin_layout Subsubsection +Random game does not work +\end_layout + +\begin_layout Standard +First of all, check that you are running with a real BIOS image. + You can tell if this is the case if PCSX ReARMed does not display a warning + at startup telling you that it could not find a BIOS file. + The internal HLE BIOS emulation is very incomplete and might cause many + games to be buggy. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +TyrQuake +\end_layout + +\begin_layout Standard +This is a Quake 1 game engine based on the open-source Quake 1 game engine + TyrQuake. + Unlike other Quake 1-based game engines, it focuses on accuracy to the + original DOS game and portability. + As such, it features no graphical enhancements and the renderer is software-bas +ed. +\end_layout + +\begin_layout Subsection +How to run +\end_layout + +\begin_layout Standard +TyrQuake does not work on its own, but runs Quake 1 PAK data archives. +\end_layout + +\begin_layout Standard +Select either pak0.pak or pak1.pak from the shareware version or the registered + version. + If the files are OK, it will start up the game. +\end_layout + +\begin_layout Subsection +How to run mission packs +\end_layout + +\begin_layout Standard +It is also possible to run mission packs with TyrQuake. +\end_layout + +\begin_layout Standard +Place the necessary files in subdirs hipnotic/ and rogue/. + Make sure the original Quake 1 datafiles are in the root directory. +\end_layout + +\begin_layout Standard +Start pak0.pak from the hipnotic/rogue directory. + Instead of launching the original game, it should now start the mission + pack. +\end_layout + +\begin_layout Subsection +Controls +\end_layout + +\begin_layout Subsubsection +RetroPad default mapping +\end_layout + +\begin_layout Standard +These are the default button mappings on the RetroPad. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Y BUTTON} +\end_layout + +\end_inset + + - Shoot +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{B BUTTON} +\end_layout + +\end_inset + + - Jump +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{A BUTTON} +\end_layout + +\end_inset + + - Weapon cycle +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{X BUTTON} +\end_layout + +\end_inset + + - (Press and hold) free look +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{L BUTTON} +\end_layout + +\end_inset + + - Strafe left +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R BUTTON} +\end_layout + +\end_inset + + - Strafe right +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{D-PAD} +\end_layout + +\end_inset + + - Movement +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{START} +\end_layout + +\end_inset + + - Bring up Options Menu +\end_layout + +\begin_layout Subsubsection +RetroPad Dual analog controls +\end_layout + +\begin_layout Standard +To enable this mode, you need to go to Core Options and set Gamepad type + to 'dual-analog'. + Your RetroPad is assumed to have two analog sticks to be able to use this + mode. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{LEFT STICK} +\end_layout + +\end_inset + + - X minus and positive X strafes left and right, Y minus and positive Y + moves forward and backwards +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{RIGHT STICK} +\end_layout + +\end_inset + + - Free look +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{R3} +\end_layout + +\end_inset + + - Center view +\end_layout + +\begin_layout Subsection +Libretro port-specific additions +\end_layout + +\begin_layout Subsubsection +Enabling/disabling software bilinear interpolation +\end_layout + +\begin_layout Standard +The original Quake software renderer had no filtering routines to speak + of for textures. + Textures would appear pixelated if you came close to them. + Enabling this (from the Quake settings menu) will apply the kernel filtering + algorithm from Unreal 1's software renderer on each texture. + This might look more aesthetically pleasing to people who prefer quasi-3D + hardware bilinear filtered textures to nearest textures. + Enabling this might come at a negligible performance cost. +\end_layout + +\begin_layout Subsubsection +Enabling/disabling mipmapping +\end_layout + +\begin_layout Standard +Normally, Quake's software renderer has this always enabled. + Objects in the distance will use lower-quality texture assets than the + ones closer to the player. + Disabling this (from the Quake settings menu) will render each object with + the most high-quality texture available, no matter what the distance is + to the player. + Enabling this will come at a big performance cost - so only enable it if + your platform is powerful enough. + +\end_layout + +\begin_layout Subsubsection +Enabling/disabling animation interpolation +\end_layout + +\begin_layout Standard +By default the game updates animations of its 3D models at a very sluggish + rate - 11 frames per second approximately. + Enabling this option (from the Quake settings menu) allows you to enable + frame interpolation so that the movements of monsters will appear much + smoother. + Enabling this might come at a negligible performance cost. +\end_layout + +\begin_layout Subsubsection +Enabling/disabling third person view +\end_layout + +\begin_layout Standard +By default, Quake is played from a first person perspective. + Enabling this option (from the Quake settings menu) allows you to play + Quake from a third person perspective. + There are two camera modes to choose from - 'Clamped' and 'Clipped'. + 'Clamped' will not allow the camera to pass through walls and it will try + to prevent showing you any of the empty 'clip space' that exists beyond + the game world. + When this 'clamping' happens, the camera will zoom in to your player. + Setting it to 'Clipped' does not bound the camera to the game world and + does not zoom in on the player - instead, it will simply show the empty + clip space that exists beyond the game world. + It is up to user preference which of the two he/she prefers. +\end_layout + +\begin_layout Subsubsection +Setting framerate to 50 or 60fps +\end_layout + +\begin_layout Standard +The original Quake never ran at a fixed framerate, and it took quite a few + years for PCs to even reach the state where they were able to run Quake + at 50 or 60fps. + Libretro TyrQuake assumes that you will want to run Quake at either a constant + 50 or 60 frames per second. + You can set the framerate to either 50fps or 60fps from the Quake settings + menu. + +\end_layout + +\begin_layout Subsection +Core options +\end_layout + +\begin_layout Subsubsection +Increasing graphics resolution +\end_layout + +\begin_layout Standard +Because Quake is using software rendered graphics and because the original + sourcecode to Quake 1 had hand-tuned assembly routines for 486/early Pentium + 1 CPUs (routines which can't be used on today's PCs), it might come as + a surprise that TyrQuake still demands high system requirements in order + to run it above the default resolution (320x200). +\end_layout + +\begin_layout Standard +By increasing the internal resolution with the core option 'Internal resolution' +, the graphical quality of the game can be significantly enhanced at the + expense of speed. + After each internal resolution change, you will need to restart the TyrQuake + core in order for the changes to be applied. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +newpage +\end_layout + +\end_inset + + +\end_layout + +\end_body +\end_document diff --git a/archive/retroarch-enduserguide.pdf b/archive/retroarch-enduserguide.pdf new file mode 100644 index 00000000..68afbd8d Binary files /dev/null and b/archive/retroarch-enduserguide.pdf differ diff --git a/archive/retroarch-manual.lyx b/archive/retroarch-manual.lyx new file mode 100644 index 00000000..694b7e21 --- /dev/null +++ b/archive/retroarch-manual.lyx @@ -0,0 +1,1832 @@ +#LyX 2.0 created this file. For more info see http://www.lyx.org/ +\lyxformat 413 +\begin_document +\begin_header +\textclass article +\use_default_options true +\maintain_unincluded_children false +\language english +\language_package default +\inputencoding auto +\fontencoding global +\font_roman default +\font_sans default +\font_typewriter default +\font_default_family default +\use_non_tex_fonts false +\font_sc false +\font_osf false +\font_sf_scale 100 +\font_tt_scale 100 + +\graphics default +\default_output_format default +\output_sync 0 +\bibtex_command default +\index_command default +\paperfontsize default +\spacing single +\use_hyperref true +\pdf_title "RetroArch Android Manual" +\pdf_author "Hans-Kristian Antzen, Daniel De Matteis" +\pdf_bookmarks true +\pdf_bookmarksnumbered false +\pdf_bookmarksopen false +\pdf_bookmarksopenlevel 1 +\pdf_breaklinks false +\pdf_pdfborder false +\pdf_colorlinks true +\pdf_backref false +\pdf_pdfusetitle true +\papersize default +\use_geometry false +\use_amsmath 1 +\use_esint 1 +\use_mhchem 1 +\use_mathdots 1 +\cite_engine basic +\use_bibtopic false +\use_indices false +\paperorientation portrait +\suppress_date false +\use_refstyle 1 +\index Index +\shortcut idx +\color #008000 +\end_index +\secnumdepth 5 +\tocdepth 5 +\paragraph_separation indent +\paragraph_indentation default +\quotes_language english +\papercolumns 1 +\papersides 1 +\paperpagestyle default +\tracking_changes false +\output_changes false +\html_math_output 0 +\html_css_as_file 0 +\html_be_strict false +\end_header + +\begin_body + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/logo.png + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Title +RetroArch Android (v0.9.8) +\end_layout + +\begin_layout Author +Hans Kristian Arntzen, Daniel De Matteis, Michael Lelli +\end_layout + +\begin_layout Standard +\begin_inset CommandInset toc +LatexCommand tableofcontents + +\end_inset + + +\end_layout + +\begin_layout Section +Introduction +\end_layout + +\begin_layout Standard +RetroArch Android is an app that has been designed to run and play: +\end_layout + +\begin_layout Itemize +Games +\end_layout + +\begin_layout Itemize +Emulators +\end_layout + +\begin_layout Standard +Emulators and games that can be run on RetroArch come in the form of pluggable + 'engines' which are called 'libretro ports'. + The version that you just installed already has most of the full library + of 'cores' preinstalled. +\end_layout + +\begin_layout Section +Disclaimer +\end_layout + +\begin_layout Standard +RetroArch Android is released for free and will always be free. + There are no ads (push or otherwise), there is no 'spying' going on in + the form of analytics or collecting stats, there is no 'paid DLC', and + on and on - all the unsavory and bad aspects of this 'new generation of + computing' are not to be found here. + It will never be sold with a pricetag - not even disguised as a 'donationware + version'. + If you happen to have 'paid' for RetroArch Android or a derivative of it, + you have been scammed and you should probably demand your money back from + the scam artist in question (and scam artists they are). +\end_layout + +\begin_layout Standard +Just because the GPL allows people to make derivative copies of RetroArch + for commercial purposes does not mean that we support it or even approve + of it. + If you sell RetroArch or a derivative copy of it for any commercial purpose, + you are part of the problem and you need to be learnt a quick lesson in + etiquette. + Note to any 'entrepreneurs' out there that might be tempted by this 'easy + route to makin' some money' - I honestly wouldn't bother - we will undercut + you by offering this all for free and doing a better job at it to boot. + That and I severely doubt you can come up with many trinkets that will + persuade people to throw away their money on a derivative version when + they can have it all for free to begin with - just saying - save yourself + the time and the effort, because it isn't going to work out. +\end_layout + +\begin_layout Section +How to run +\end_layout + +\begin_layout Subsection +Select a core +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/maE85W6.png + lyxscale 50 + scale 30 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{Select a core from this menu.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/UhU7QrR.png + lyxscale 50 + scale 30 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{After selecting the core, you will need to load a game.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +A 'libretro core' supports games with certain extensions. + Below you will find the list of cores that came preinstalled with this + app and what file extensions they support. +\end_layout + +\begin_layout Itemize +SNES9x Next +\begin_inset Newline newline +\end_inset + +Used for: playing SNES games (Super Nintendo Entertainment System) +\begin_inset Newline newline +\end_inset + +Author(s): SNES9x team, OV2, Bearoso, zones, Squarepusher (fork) +\begin_inset Newline newline +\end_inset + +Recommended system requirements: ARM Cortex A9 multi-core device (and up) +\begin_inset Newline newline +\end_inset + +Extensions: "smc|fig|sfc|gd3|gd7|dx2|bsx|swc|zip|SMC|FIG| +\begin_inset Newline newline +\end_inset + +SFC|BSX|GD3|GD7|DX2|SWC|ZIP" +\end_layout + +\begin_layout Itemize +VBA Next +\begin_inset Newline newline +\end_inset + +Used for: playing Game Boy Advance games +\begin_inset Newline newline +\end_inset + +Recommended system requirements: ARM Cortex A9 multi-core based device (and + up) +\begin_inset Newline newline +\end_inset + +Author(s): Forgotten, VBA-M team, Squarepusher (fork) +\begin_inset Newline newline +\end_inset + +Extensions: "gba|GBA|zip|ZIP" +\end_layout + +\begin_layout Itemize +FCEUmm +\begin_inset Newline newline +\end_inset + +Used for: playing NES games (Nintendo Entertainment System) +\begin_inset Newline newline +\end_inset + +Author(s): CaH4e3, original FCEU authors +\begin_inset Newline newline +\end_inset + +Extensions: "fds|FDS|zip|ZIP|nes|NES|unif|UNIF" +\end_layout + +\begin_layout Itemize +NEStopia +\begin_inset Newline newline +\end_inset + +Used for: playing NES games (Nintendo Entertainment System) +\begin_inset Newline newline +\end_inset + +Author(s): Marty +\begin_inset Newline newline +\end_inset + +Extensions supported: "nes|NES|zip|ZIP|fds|FDS" +\end_layout + +\begin_layout Itemize +Gambatte +\begin_inset Newline newline +\end_inset + +Used for: playing GameBoy / GameBoy Color games +\begin_inset Newline newline +\end_inset + +Author(s): Sinamas +\begin_inset Newline newline +\end_inset + +Extensions supported: "gb|gbc|dmg|zip|GB|GBC|DMG|ZIP" +\end_layout + +\begin_layout Itemize +Final Burn Alpha +\begin_inset Newline newline +\end_inset + +Used for: playing arcade games +\begin_inset Newline newline +\end_inset + +Author(s): Dave, FBA Team (Barry Harris & co) +\begin_inset Newline newline +\end_inset + +Extensions supported: +\begin_inset Quotes eld +\end_inset + +zip|ZIP +\begin_inset Quotes erd +\end_inset + + +\end_layout + +\begin_layout Itemize +Genesis Plus GX +\begin_inset Newline newline +\end_inset + +Used for: playing Sega Genesis / Master System / Game Gear / Sega CD games +\begin_inset Newline newline +\end_inset + +Author(s): Charles McDonald, ekeeke +\begin_inset Newline newline +\end_inset + +Extensions supported: "md|smd|bin|cue|gen|zip|MD|SMD|bin|iso| +\begin_inset Newline newline +\end_inset + +ISO|CUE|GEN|ZIP|sms|SMS|gg|GG|sg|SG" +\end_layout + +\begin_layout Itemize +NX Engine +\begin_inset Newline newline +\end_inset + +Used for: playing Cave Story / Doukutsu Monogatari +\begin_inset Newline newline +\end_inset + +Author(s): Caitlin Shaw (rogueeve) +\begin_inset Newline newline +\end_inset + +Extensions supported: +\begin_inset Quotes eld +\end_inset + +exe|EXE|zip|ZIP +\begin_inset Quotes erd +\end_inset + + +\end_layout + +\begin_layout Itemize +PCSX ReARMed +\begin_inset Newline newline +\end_inset + +Used for: playing PlayStation1 games +\begin_inset Newline newline +\end_inset + +Author(s): PCSX Team, Notaz, Exophase (GPU plugin) +\begin_inset Newline newline +\end_inset + +Extensions supported: "bin|cue|img|mdf|pbp|cbn" +\end_layout + +\begin_layout Itemize +Prboom +\begin_inset Newline newline +\end_inset + +Used for: playing Doom, Doom 2, Ultimate Doom, Final Doom, and mods +\begin_inset Newline newline +\end_inset + +Author(s): Various +\begin_inset Newline newline +\end_inset + +Extensions supported: "WAD|wad|IWAD|iwad" +\end_layout + +\begin_layout Itemize +Mednafen NGP +\begin_inset Newline newline +\end_inset + +Used for: playing Neo Geo Pocket Color games +\begin_inset Newline newline +\end_inset + +Author(s): Original Neopop authors, Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "ngp|NGP|ngc|NGC|zip|ZIP" +\end_layout + +\begin_layout Itemize +Mednafen WonderSwan +\begin_inset Newline newline +\end_inset + +Used for: playing WonderSwan / WonderSwan Color / WonderSwan Crystal games +\begin_inset Newline newline +\end_inset + +Author(s): Original Cygne authors, Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "ws|WS|wsc|WSC|zip|ZIP" +\end_layout + +\begin_layout Itemize +Mednafen Virtual Boy +\begin_inset Newline newline +\end_inset + +Used for: playing Virtual Boy games +\begin_inset Newline newline +\end_inset + +Author: Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "vb|VB|vboy|VBOY|bin|BIN|zip|ZIP" +\end_layout + +\begin_layout Itemize +Mednafen PC Engine +\begin_inset Newline newline +\end_inset + +Used for: playing PC Engine / Supergrafx 16 / PC Engine CD games +\begin_inset Newline newline +\end_inset + +Author: Ryphecha +\begin_inset Newline newline +\end_inset + +Extensions supported: "pce|PCE|sgx|SGX|cue|CUE|zip|ZIP" +\end_layout + +\begin_layout Standard +Select one of these cores in the menu. +\end_layout + +\begin_layout Subsection +Select a game +\end_layout + +\begin_layout Standard +After you have selected a core, you will need to select a compatible game + from the filebrowser. + It will then attempt to load the core with that specific game. +\end_layout + +\begin_layout Section +Controls +\end_layout + +\begin_layout Subsection +Touchscreen overlay +\end_layout + +\begin_layout Standard +RetroArch Android uses an overlay as a 'mock' gamepad to play with. + The 'overlay' controls will always be bound to Player 1. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/Rr2Nvgo.png + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Gamepad overlay' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsection +Touchscreen menu navigation +\end_layout + +\begin_layout Standard +Each touchscreen overlay has a couple of screens that can be navigated to. + To go to the next screen of the overlay, you press the 'circle' icon at + the bottom. +\end_layout + +\begin_layout Standard +Most of the overlays that come bundled with RetroArch Android have the same + screen order. +\end_layout + +\begin_layout Subsubsection +Gamepad screen +\end_layout + +\begin_layout Standard +You can control the game with this screen. + Illustrated is a controller called 'RetroPad'. + It is laid out like a SNES pad with PlayStation-style shoulder +\end_layout + +\begin_layout Standard +buttons. +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/1ZhxUo2.png + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Quick Menu' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +Quick Menu screen +\end_layout + +\begin_layout Standard +The actions on this screen have various effects on the game currently running. +\end_layout + +\begin_layout Itemize +LOAD STATE - Load a save state from the currently selected save state slot. +\end_layout + +\begin_layout Itemize +SAVE STATE - Save state to the currently selected save state slot. +\end_layout + +\begin_layout Itemize +STATE MINUS - Go back one save state slot. +\end_layout + +\begin_layout Itemize +STATE PLUS - Go forward one state slot. +\end_layout + +\begin_layout Itemize +REWIND - Rewind the game in real-time. + Note - the 'Rewind' option needs to be enabled at the Settings menu or + else this option won't work. +\end_layout + +\begin_layout Itemize +SLOWMOTION - Press and hold this button to let the game run in slowmotion. +\end_layout + +\begin_layout Itemize +RESET - Resets the game/system. +\end_layout + +\begin_layout Itemize +FAST FORWARD - Fast forward the game in real-time. +\end_layout + +\begin_layout Itemize +NEXT SHADER - Load the next shader in the folder (NOTE: only if shaders + are enabled) +\end_layout + +\begin_layout Itemize +PREVIOUS SHADER - Load the previous shader in the folder (NOTE: only if + shaders are enabled) +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/hCwKqVN.png + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Gameplay' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +Gameplay screen +\end_layout + +\begin_layout Standard +This screen is useful for when you are playing with an USB or Bluetooth + gamepad but you would still like to have access to the Quick Menu or Gamepad + screen without outright disabling overlays. + If you press the 'icon' at the bottom of this screen, you will go back + to the 'Gamepad' screen'. +\end_layout + +\begin_layout Subsection +Variations +\end_layout + +\begin_layout Standard +RetroArch Android comes packaged with a number of different-looking overlays. + You can select from a number of different overlays in the Settings menu. + Below is a list of different overlays: +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/overlays.png + lyxscale 50 + scale 50 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{All the default overlays packaged with RetroArch Android.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Subsubsection +Making your own custom overlays +\end_layout + +\begin_layout Standard +You can make your own custom overlays for use with RetroArch Android. + If you want to learn how to do this, you should read the 'Overlay Guide'. +\end_layout + +\begin_layout Subsection +USB gamepads +\end_layout + +\begin_layout Standard +Next to the standard touchscreen input, RetroArch Android autodetects and + autoconfigures various input devices automatically. + Most of these are USB joysticks/gamepads. +\end_layout + +\begin_layout Standard +A list of the gamepads that are supported by autodetection can be found + inside the app. + (go to Help). +\end_layout + +\begin_layout Standard +You connect the device to your tablet/phone. + You press a button while ingame. + If your pad is supported, it should bring up a message saying: +\begin_inset Quotes eld +\end_inset + +RetroPad #? detected: +\begin_inset Quotes eld +\end_inset + + and then the name of the device it found. + Buttons and control layout will then be autoconfigured and mapped to the + RetroPad layout. +\end_layout + +\begin_layout Subsubsection +Unsupported gamepads +\end_layout + +\begin_layout Standard +If your pad is unsupported, it will likely show +\begin_inset Quotes eld +\end_inset + +Unknown HID +\begin_inset Quotes erd +\end_inset + + instead. + If you want this pad supported, contact us. +\end_layout + +\begin_layout Subsubsection +Notes +\end_layout + +\begin_layout Standard +If a USB gamepad that is listed above does not work immediately, your controller + may require a powered USB hub or perhaps a HID driver may be missing of + sorts. +\end_layout + +\begin_layout Subsection +Bluetooth +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/sVWyw8c.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{Setting an IME app from the RetroArch menu by clicking on the 'Settings' + icon.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +RetroArch supports Bluetooth right now only through the use of IME apps. + A couple of IME apps are supported by RetroArch Android - if you use the + default key layouts with the IME apps listed below, your pads will be automatic +ally configured: +\end_layout + +\begin_layout Itemize +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://play.google.com/store/apps/details?id=com.dancingpixelstudios.sixaxiscontrol +ler +\end_layout + +\end_inset + + Dancing Pixel Studios SixAxis Controller +\end_layout + +\begin_layout Itemize +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://play.google.com/store/apps/details?id=com.ccpcreations.android.WiiUseAndroid +\end_layout + +\end_inset + + ccpcreations.Wiiuse.Android +\end_layout + +\begin_layout Standard +Remember that you will have to change your Input Method to the needed IME + first before starting RetroArch. + This can also be done from the menu by clicking on the top righthand side + 'Settings' icon and then selecting 'Input Method' (see image). +\end_layout + +\begin_layout Subsection +Notes +\end_layout + +\begin_layout Standard +When using PS3 controller via Bluetooth, use SixAxis adapter app and after + you've got the controller setup, make sure to go to menu then preferences + and then Game pad settings, and enable Gamepad. + This turns it into a native android controller and no IME switch is needed. + Same for the MOGA controller via bluetooth, make sure to use the MOGA Universal + Driver and not the one that MOGA recommends. + In the app, make sure 'Enable left analog input' is checked, and that it's + in System Mode to make it a native gamepad for android and no need to switch + IMEs. +\end_layout + +\begin_layout Section +Settings +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/Emu9nsQ.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Settings' menu.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +You can configure many aspects of RetroArch. + To go to the Settings menu, click on the 'Settings' icon at the top righthand + side of the screen and then select 'Settings'. +\end_layout + +\begin_layout Subsection +Path Settings +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/4i6EGD7.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Path Settings' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +ROM Directory +\begin_inset Newline newline +\end_inset + +Set the directory that will be used as a default starting point for the + filebrowser. +\end_layout + +\begin_layout Itemize +Save Files - Enable custom directory +\begin_inset Newline newline +\end_inset + +Enables use of custom save file folder. + (.srm) save files will be saved and loaded to the configured directory. + if not enabled, save files will reside in ROM folder. +\end_layout + +\begin_layout Itemize +Save Files - Savefile directory +\begin_inset Newline newline +\end_inset + +Sets directory where to save and load game save files. +\end_layout + +\begin_layout Itemize +Save States - Enable custom directory +\begin_inset Newline newline +\end_inset + +Enables use of custom save statefolder. + (.state) save states will be saved and loaded to configured directory. + If not enabled, save states will reside in ROM folder. +\end_layout + +\begin_layout Itemize +Save state directory +\begin_inset Newline newline +\end_inset + +Sets directory where to save and load game save states. +\end_layout + +\begin_layout Subsection +System Settings +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/WOfUmx7.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'System Settings' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Auto load state +\begin_inset Newline newline +\end_inset + +Loads an automatically created savestate at startup. +\end_layout + +\begin_layout Itemize +Auto save state +\begin_inset Newline newline +\end_inset + +This will make a save state when you exit the game. + This auto savestate will be automatically loaded the next time you start + up the +\begin_inset Newline newline +\end_inset + +game. + Useful for on-the-go gaming. +\end_layout + +\begin_layout Itemize +Rewinding Enable +\begin_inset Newline newline +\end_inset + +This allows you to rewind the game in real-time to undo 'mistakes' you made + while playing the game. + (NOTE - this is very CPU intensive - you should only enable this if the + core is running at least 2x realtime on your system). +\end_layout + +\begin_layout Subsection +Video Settings +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/3gbr7az.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Video Settings' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Vsync +\begin_inset Newline newline +\end_inset + +Unchecking this will cause screen tearing but faster performance. +\end_layout + +\begin_layout Itemize +Sync refreshrate to screen +\begin_inset Newline newline +\end_inset + +Synchronize RetroArch's refresh rate to the screen's refresh rate (recommended + - some screens have refresh rates below 59.95Hz and need this enabled to + get good audio/video sync). +\end_layout + +\begin_layout Itemize +Forced refresh rate (Hz) +\begin_inset Newline newline +\end_inset + +Force a specific refresh rate to be detected. + Only use this if auto-detection of refresh rate reports wrong refresh rate. +\end_layout + +\begin_layout Itemize +Auto-rotate +\begin_inset Newline newline +\end_inset + +Will auto-rotate the screen for vertically oriented games. +\end_layout + +\begin_layout Itemize +Aspect ratio +\begin_inset Newline newline +\end_inset + +Select the aspect ratio to enforce. +\end_layout + +\begin_layout Itemize +Shaders (1st pass) Bilinear filter +\begin_inset Newline newline +\end_inset + +Applies bilinear filtering, smooths out edges (setting still apply even + if no shader is selected). +\end_layout + +\begin_layout Itemize +Shaders (1st pass) Enable +\begin_inset Newline newline +\end_inset + +Enable the currently selected shader. +\end_layout + +\begin_layout Itemize +Shaders (1st pass) XML Shader +\begin_inset Newline newline +\end_inset + +Select this option to select a shader from the filesystem. + RetroArch comes prepackaged with a collection of shaders. +\end_layout + +\begin_layout Itemize +Shaders (Multi-pass) Render-to-texture +\begin_inset Newline newline +\end_inset + +Render first pass to a texture (FBO). + Stretch to screen with second shader. +\end_layout + +\begin_layout Itemize +Shaders (Multi-pass) Enable shader #2 +\begin_inset Newline newline +\end_inset + +Enable custom shader or use after rendering to FBO. +\end_layout + +\begin_layout Itemize +Shaders (Multi-pass) XML shder (2nd pass) +\begin_inset Newline newline +\end_inset + +Sets shader to use for second-pass. +\end_layout + +\begin_layout Itemize +Shaders (Multi-pass) FBO Scale +\begin_inset Newline newline +\end_inset + +Scale to use when rendering to FBO. +\end_layout + +\begin_layout Itemize +Shaders (Multi-pass) Second-pass bilinear filtering +\begin_inset Newline newline +\end_inset + +Use bilinear filtering on FBO texture on second pass. +\end_layout + +\begin_layout Itemize +Enable on-screen fonts +\begin_inset Newline newline +\end_inset + +Enable rendering of on-screen fonts for system messages. +\end_layout + +\begin_layout Subsubsection +Notes on shaders +\end_layout + +\begin_layout Itemize +The shaders that come prepackaged with RetroArch Android come from the PS3 + and Xbox 360 ports of RetroArch. + Unfortunately, most Android GPUs are very weak compared to the ones inside + the PS3 and 360 - so most of these shaders will run extemely slow on nearly + all Android devices right now. + To make these shaders usable we will have to wait until GPUs on Android-powered + devices catch up with PS3 and 360. + They will make for good GPU benchmarks in the meantime - these shaders + are far more intensive on the GPU than the trivial 'shaders' used in commercial + games - which are mostly used for menial tasks instead of applying an expensive + image-enhancing algorithm to the entire screen like the 'shader filters' + seen here. +\end_layout + +\begin_layout Subsubsection +Notes on refresh rate +\end_layout + +\begin_layout Itemize +Some devices (like the Samsung Galaxy S3) falsely report that the screen + refresh rate is 60Hz. + For these devices, it is recommended that you set 'forced refresh rate' + manually to a lower rate until you find the right value that gives you + good audio/video with no audio pops. +\end_layout + +\begin_layout Subsection +Audio Settings +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/UVU6Chp.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Audio Settings' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Audio Enable +\begin_inset Newline newline +\end_inset + +Uncheck this to disable sound. +\end_layout + +\begin_layout Itemize +Dynamic Rate Control +\begin_inset Newline newline +\end_inset + +Dynamic rate control tries to prevent sound pops by dynamically adjusting + samplerate. + It is recommended that you leave this on for RetroArch Android. +\end_layout + +\begin_layout Subsection +Input Settings +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +begin{figure} +\backslash +begin{centering} +\end_layout + +\end_inset + + +\begin_inset Graphics + filename retroarch-android/deYDWvd.png + lyxscale 50 + scale 35 + clip + +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +caption{'Input Settings' screen.} +\backslash +end{centering} +\backslash +end{figure} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize +Configuration Autodetect Enable +\begin_inset Newline newline +\end_inset + +This will attempt to preconfigure various gamepads and/or IME apps that + you connect. +\end_layout + +\begin_layout Itemize +Debug Input Reporting Enable +\begin_inset Newline newline +\end_inset + +This will report keycodes onscreen generated by your input device(s). + You should use this option when you want us to support a gamepad that you + use. + You should use this option then to see which keycodes are generated by + all the buttons on your gamepad/input device and then report this back + to us. +\end_layout + +\begin_layout Itemize +Touchscreen Overlay Enable +\begin_inset Newline newline +\end_inset + +You can disable the overlay system entirely by disabling this. +\end_layout + +\begin_layout Itemize +Input overlay +\begin_inset Newline newline +\end_inset + +You can select a different overlay by choosing this option. +\end_layout + +\begin_layout Section +RetroArch on other platforms +\end_layout + +\begin_layout Standard +RetroArch isn't only available for Android. + It is available on other platforms as well, including: +\end_layout + +\begin_layout Itemize +PlayStation3 +\end_layout + +\begin_layout Itemize +Xbox 1 +\end_layout + +\begin_layout Itemize +Xbox 360 +\end_layout + +\begin_layout Itemize +Wii/Gamecube +\end_layout + +\begin_layout Itemize +Raspberry Pi +\end_layout + +\begin_layout Itemize +PC (Mac/Linux/Windows) +\end_layout + +\begin_layout Standard +And it will be ported to even more platforms in the future. + You might even see the libretro cores running in XBMC shortly. +\end_layout + +\begin_layout Section +About Us +\end_layout + +\begin_layout Standard +Homepage: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +http://www.libretro.org +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +IRC: #retroarch at freenode +\begin_inset Newline newline +\end_inset + +Github (libretro organization): +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://github.com/libretro +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +RetroArch @ Github: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://github.com/Themaister/RetroArch +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +Libretro @ Twitter: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://twitter.com/libretro +\end_layout + +\end_inset + + +\begin_inset Newline newline +\end_inset + +Libretro @ Facebook: +\begin_inset Flex URL +status collapsed + +\begin_layout Plain Layout + +https://www.facebook.com/libretro.retroarch +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Credits +\end_layout + +\begin_layout Standard +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{RetroArch Android} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Hans-Kristian Arntzen (Themaister) +\end_layout + +\begin_layout Standard +Daniel De Matteis (Squarepusher2/Twinaphex) +\end_layout + +\begin_layout Standard +Michael Lelli (ToadKing) +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{RetroArch Android contributions} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Meancoot +\end_layout + +\begin_layout Standard +Opium2k (overlay images) +\begin_inset Newline newline +\end_inset + + +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +textbf{Thanks to} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Notaz (PCSX ReARMed libretro port - RetroArch ARM Linux patches) +\end_layout + +\begin_layout Standard +FBA Team (for adopting libretro upstream - FBA) +\end_layout + +\begin_layout Standard +Ekeeke (for adopting libretro upstream - Genesis Plus GX) +\end_layout + +\begin_layout Standard +CaH4e3 (for adopting libretro upstream - FCEUmm) +\end_layout + +\begin_layout Standard +Rdanbrook (for adopting libretro upstream - NEStopia Undead) +\end_layout + +\begin_layout Standard +XBMC devs (for adopting libretro vis a vis RetroPlayer) +\end_layout + +\begin_layout Standard +Zeromus +\end_layout + +\end_body +\end_document diff --git a/archive/shader-rarch-2.jpg b/archive/shader-rarch-2.jpg new file mode 100644 index 00000000..0fe3e1ef Binary files /dev/null and b/archive/shader-rarch-2.jpg differ diff --git a/archive/supermetroid.jpg b/archive/supermetroid.jpg new file mode 100644 index 00000000..c0b7585e Binary files /dev/null and b/archive/supermetroid.jpg differ diff --git a/docs/image/development/shaders/content-aware-shader-1.jpg b/docs/image/development/shaders/content-aware-shader-1.jpg new file mode 100644 index 00000000..37053eda Binary files /dev/null and b/docs/image/development/shaders/content-aware-shader-1.jpg differ diff --git a/docs/image/development/shaders/content-aware-shader-1.png b/docs/image/development/shaders/content-aware-shader-1.png deleted file mode 100644 index 0b993e63..00000000 Binary files a/docs/image/development/shaders/content-aware-shader-1.png and /dev/null differ diff --git a/docs/image/development/shaders/content-aware-shader-2.jpg b/docs/image/development/shaders/content-aware-shader-2.jpg new file mode 100644 index 00000000..ba307f64 Binary files /dev/null and b/docs/image/development/shaders/content-aware-shader-2.jpg differ diff --git a/docs/image/development/shaders/content-aware-shader-2.png b/docs/image/development/shaders/content-aware-shader-2.png deleted file mode 100644 index 1343dc59..00000000 Binary files a/docs/image/development/shaders/content-aware-shader-2.png and /dev/null differ diff --git a/docs/tech/content-aware-shaders.md b/docs/tech/content-aware-shaders.md index 695409a9..6e536ebb 100644 --- a/docs/tech/content-aware-shaders.md +++ b/docs/tech/content-aware-shaders.md @@ -146,7 +146,7 @@ To develop these kinds of shaders, I’d recommend using RetroArch w/Cg support, Here are some screenshots of the mario effect (in Super Mario World SNES) we developed. Obviously this is a very simple example showing what can be done. The imagination is the limit here. ### Prior to Mario jumping in water -![Super Mario World prior to Mario jumping in water.](../image/development/shaders/content-aware-shader-1.png) +![Super Mario World prior to Mario jumping in water.](../image/development/shaders/content-aware-shader-1.jpg) ### After Mario jumps in water -![Super Mario World after Mario jumps in water](../image/development/shaders/content-aware-shader-2.png) +![Super Mario World after Mario jumps in water](../image/development/shaders/content-aware-shader-2.jpg) diff --git a/docs/tech/dynamic-rate-control.md b/docs/tech/dynamic-rate-control.md index fd13dd48..aeaac7e2 100644 --- a/docs/tech/dynamic-rate-control.md +++ b/docs/tech/dynamic-rate-control.md @@ -4,7 +4,32 @@ Dynamic Rate Control allows emulator frontends to synchronize both audio and vid The method works by dynamically adjusting audio resampling ratios in such ways that ideally, the audio buffer is never underrun nor overrun, thus avoiding blocking on audio. This in turn allows vertical synchronization for video. The audio pitch is adjusted when adjusting audio resampling ratios, but in practice so little, that it is inaudible to the human ear. -### Read this documenation in PDF form +!!! Tip "Read this documenation in PDF form" + Because the formulas in this documenation have not yet been converted to markdown, [please consult the original PDF version](https://github.com/libretro/docs/blob/master/archive/ratecontrol.pdf). _If you can assist in the conversion, please post an issue or PR in [the libretro documentation repository](https://github.com/libretro/docs)._ -Because this documenation has not yet been converted to the new format, [please consult the original PDF version](https://github.com/libretro/docs/blob/master/archive/ratecontrol.pdf). +Retro games are highly synchronous. Their audio output rates are linked directly to video refresh rates. Every video frame, the audio chip generates on average a fixed amount of audio samples. Before continuing to emulate the next frame, the generated audio samples must be pushed to an audio buffer of fixed size. +If there is not enough space in the audio buffer, the emulator must wait (block) for the buffer to become ready for writing. This is a non-ideal situation as while the emulator is blocking on audio, a vertical refresh might be missed entirely, thus creating stuttering video. + +## Ideal synchronization + +For an emulator of a retro game system, a key factor in smooth video is vertical refresh synchronization (**VSync**), where each frame of the game maps to a single frame on the monitor. Audio must also be pushed to the speakers without any audio dropouts. This double synchronization requirement poses a problem as any form of synchronization to one modality will negatively affect the other. + +This is a real problem as an emulator has no way of guaranteeing perfectly equal video refresh rates and audio sampling rates as the original system. + +On conventional computer hardware, there is no perfect way of knowing the real monitor refresh rates and audio sampling rates either due to tolerances on oscillators. + + +## Scope of method + +As this method aims to implement a method for synchronization when VSync is used, this method is only useful when game frame rate is close to monitor frame rate. If this is not the case, other methods should be employed. + + +## Method + +This method assumes that audio from the emulator is output at regular intervals, e.g. every video frame. The method also assumes that audio is resampled from the game system sampling rate to the sound cards sampling rate. The resampling ratio will be dynamically adjusted every time audio is resampled and subsequently pushed to the audio buffer. + + +## Link to full version + +Because the formulas in this documenation have not yet been converted to markdown, [please consult the original PDF version](https://github.com/libretro/docs/blob/master/archive/ratecontrol.pdf). _If you can assist in the conversion, please post an issue or PR in [the libretro documentation repository](https://github.com/libretro/docs)._ \ No newline at end of file