Package com.jme3.renderer

Interface Renderer

All Known Implementing Classes:
GLRenderer, NullRenderer
public interface Renderer
Responsible for taking rendering commands and executing them on the underlying video hardware.

  • Method Details

    • initialize

      void initialize()
      Detects available capabilities of the GPU. Must be called prior to any other Renderer methods.

    • getCaps

      EnumSet<Caps> getCaps()
      Gets the capabilities of the renderer.
      Returns:
      The capabilities of the renderer.

    • getLimits

      EnumMap<Limits,Integer> getLimits()
      Gets the limits of the renderer.
      Returns:
      The limits of the renderer.

    • getStatistics

      Statistics getStatistics()
      Copies the render statistics.

      The statistics allow tracking of how data per frame, such as number of objects rendered, number of triangles, etc. These are updated when the Renderer's methods are used, make sure to call Statistics.clearFrame() at the appropriate time to get accurate info per frame.

      Returns:
      a new instance

    • invalidateState

      void invalidateState()
      Invalidates the current rendering state. Should be called after the GL state was changed manually or through an external library.

    • clearBuffers

      void clearBuffers(boolean color, boolean depth, boolean stencil)
      Clears certain channels of the currently bound framebuffer.
      Parameters:
      color - True if to clear colors (RGBA)
      depth - True if to clear depth/z
      stencil - True if to clear stencil buffer (if available, otherwise ignored)

    • setBackgroundColor

      void setBackgroundColor(ColorRGBA color)
      Sets the background (aka clear) color.
      Parameters:
      color - The background color to set

    • applyRenderState

      void applyRenderState(RenderState state)
      Applies the given RenderState, making the necessary GL calls so that the state is applied.
      Parameters:
      state - the RenderState to apply

    • setDepthRange

      void setDepthRange(float start, float end)
      Sets the range of the depth values for objects. All rendered objects will have their depth clamped to this range.
      Parameters:
      start - The range start
      end - The range end

    • postFrame

      void postFrame()
      Called when a new frame has been rendered. Currently, this will simply delete any OpenGL objects from the GPU which have been garbage collected by the GC.

    • setViewPort

      void setViewPort(int x, int y, int width, int height)
      Sets the viewport location and resolution on the screen.
      Parameters:
      x - The x coordinate of the viewport
      y - The y coordinate of the viewport
      width - Width of the viewport
      height - Height of the viewport

    • setClipRect

      void setClipRect(int x, int y, int width, int height)
      Specifies a clipping rectangle. For all future rendering commands, no pixels will be allowed to be rendered outside of the clip rectangle.
      Parameters:
      x - The x coordinate of the clip rect
      y - The y coordinate of the clip rect
      width - Width of the clip rect
      height - Height of the clip rect

    • clearClipRect

      void clearClipRect()
      Clears the clipping rectangle set with setClipRect(int, int, int, int).

    • setShader

      void setShader(Shader shader)
      Sets the shader to use for rendering. If the shader has not been uploaded yet, it is compiled and linked. If it has been uploaded, then the uniform data is updated and the shader is set.
      Parameters:
      shader - The shader to use for rendering.

    • deleteShader

      void deleteShader(Shader shader)
      Deletes a shader. This method also deletes the attached shader sources.
      Parameters:
      shader - Shader to delete.
      See Also:

    • deleteShaderSource

      void deleteShaderSource(Shader.ShaderSource source)
      Deletes the provided shader source.
      Parameters:
      source - The ShaderSource to delete.

    • copyFrameBuffer

      @Deprecated void copyFrameBuffer(FrameBuffer src, FrameBuffer dst, boolean copyDepth)
      Deprecated.
      Use copyFrameBuffer(com.jme3.texture.FrameBuffer, com.jme3.texture.FrameBuffer, boolean, boolean).
      Copies contents from src to dst, scaling if necessary. set copyDepth to false to only copy the color buffers.
      Parameters:
      src - the source FrameBuffer (unaffected)
      dst - the destination FrameBuffer (modified)
      copyDepth - true→copy depth info, false→don't copy it

    • copyFrameBuffer

      void copyFrameBuffer(FrameBuffer src, FrameBuffer dst, boolean copyColor, boolean copyDepth)
      Copies contents from src to dst, scaling if necessary.
      Parameters:
      src - the source FrameBuffer (unaffected)
      dst - the destination FrameBuffer (modified)
      copyColor - true→copy color info, false→don't copy it
      copyDepth - true→copy depth info, false→don't copy it

    • setFrameBuffer

      void setFrameBuffer(FrameBuffer fb)
      Sets the framebuffer that will be drawn to. If the framebuffer has not been initialized yet, it will be created and its render surfaces and attached textures will be allocated.
      Parameters:
      fb - The framebuffer to set

    • setMainFrameBufferOverride

      void setMainFrameBufferOverride(FrameBuffer fb)
      Sets the framebuffer that will be set instead of the main framebuffer when a call to setFrameBuffer(null) is made.
      Parameters:
      fb - The framebuffer to override the main framebuffer.

    • readFrameBuffer

      void readFrameBuffer(FrameBuffer fb, ByteBuffer byteBuf)
      Reads the pixels currently stored in the specified framebuffer into the given ByteBuffer object. Only color pixels are transferred, the format is RGBA with 8 bits per component. The given byte buffer should have at least fb.getWidth() * fb.getHeight() * 4 bytes remaining.
      Parameters:
      fb - The framebuffer to read from
      byteBuf - The bytebuffer to transfer color data to

    • readFrameBufferWithFormat

      void readFrameBufferWithFormat(FrameBuffer fb, ByteBuffer byteBuf, Image.Format format)
      Reads the pixels currently stored in the specified framebuffer into the given ByteBuffer object. Only color pixels are transferred, with the given format. The given byte buffer should have at least fb.getWidth() * fb.getHeight() * 4 bytes remaining.
      Parameters:
      fb - The framebuffer to read from
      byteBuf - The bytebuffer to transfer color data to
      format - the image format to use when reading the frameBuffer.

    • deleteFrameBuffer

      void deleteFrameBuffer(FrameBuffer fb)
      Deletes a framebuffer and all attached renderbuffers.
      Parameters:
      fb - the FrameBuffer to be deleted

    • setTexture

      void setTexture(int unit, Texture tex) throws TextureUnitException
      Assigns a Texture to the specified texture unit.
      Parameters:
      unit - the index of the texture unit (≥0)
      tex - the Texture to assign
      Throws:
      TextureUnitException - if the texture unit doesn't exist

    • modifyTexture

      void modifyTexture(Texture tex, Image pixels, int x, int y)
      Modifies the given Texture with the given Image. The image will be put at x and y into the texture. NOTE: this is only supported for uncompressed 2D images without mipmaps.
      Parameters:
      tex - the Texture that will be modified
      pixels - the source Image data to copy data from
      x - the x position to put the image into the texture
      y - the y position to put the image into the texture

    • deleteImage

      void deleteImage(Image image)
      Deletes a texture from the GPU.
      Parameters:
      image - the texture to delete

    • updateBufferData

      void updateBufferData(VertexBuffer vb)
      Uploads a vertex buffer to the GPU.
      Parameters:
      vb - The vertex buffer to upload

    • updateBufferData

      void updateBufferData(BufferObject bo)
      Uploads data of the buffer object on the GPU.
      Parameters:
      bo - the buffer object to upload.

    • deleteBuffer

      void deleteBuffer(VertexBuffer vb)
      Deletes a vertex buffer from the GPU.
      Parameters:
      vb - The vertex buffer to delete

    • deleteBuffer

      void deleteBuffer(BufferObject bo)
      Deletes the buffer object from the GPU.
      Parameters:
      bo - the buffer object to delete.

    • renderMesh

      void renderMesh(Mesh mesh, int lod, int count, VertexBuffer[] instanceData)
      Renders count meshes, with the geometry data supplied and per-instance data supplied. The shader which is currently set with setShader is responsible for transforming the input vertices into clip space and shading it based on the given vertex attributes. The integer variable gl_InstanceID can be used to access the current instance of the mesh being rendered inside the vertex shader. If the instance data is non-null, then it is submitted as a per-instance vertex attribute to the shader.
      Parameters:
      mesh - The mesh to render
      lod - The LOD level to use, see Mesh.setLodLevels(com.jme3.scene.VertexBuffer[]).
      count - Number of mesh instances to render
      instanceData - When count is greater than 1, these buffers provide the per-instance attributes.

    • resetGLObjects

      void resetGLObjects()
      Resets all previously used Native Objects on this Renderer. The state of the native objects is reset in such way, that using them again will cause the renderer to reupload them. Call this method when you know the GL context is going to shut down.
      See Also:

    • cleanup

      void cleanup()
      Deletes all previously used Native Objects on this Renderer, and then resets the native objects.
      See Also:

    • setDefaultAnisotropicFilter

      void setDefaultAnisotropicFilter(int level)
      Sets the default anisotropic filter level for textures.

      If the texture anisotropic filter is set to 0, then the default level is used. Otherwise, if the texture level is 1 or greater, then the texture's value overrides the default value.

      Parameters:
      level - The default anisotropic filter level to use. Default: 1.
      Throws:
      IllegalArgumentException - If level is less than 1.

    • setAlphaToCoverage

      void setAlphaToCoverage(boolean value)
      Sets the alpha to coverage state.

      When alpha coverage and multi-sampling is enabled, each pixel will contain alpha coverage in all of its subsamples, which is then combined when other future alpha-blended objects are rendered.

      Alpha-to-coverage is useful for rendering transparent objects without having to worry about sorting them.

      Parameters:
      value - true to enable alpha coverage, otherwise false

    • setMainFrameBufferSrgb

      void setMainFrameBufferSrgb(boolean srgb)
      Specifies whether color values in the main framebuffer are in SRGB format.

      If enabled, color values rendered to the main framebuffer undergo linear -> sRGB conversion.

      This is identical to FrameBuffer.setSrgb(boolean) except it is toggled for the main framebuffer instead of an offscreen buffer.

      This should be set together with setLinearizeSrgbImages(boolean)

      As a shorthand, the user can set AppSettings.setGammaCorrection(boolean) to true to toggle both setLinearizeSrgbImages(boolean) and setMainFrameBufferSrgb(boolean) if the Caps.Srgb is supported by the GPU.

      Parameters:
      srgb - true for sRGB colorspace, false for linear colorspace
      Throws:
      RendererException - If the GPU hardware does not support sRGB.
      See Also:

    • setLinearizeSrgbImages

      void setLinearizeSrgbImages(boolean linearize)
      If enabled, all images with the sRGB flag set shall undergo an sRGB to linear RGB color conversion when read by a shader.

      The conversion is performed for the following formats: - Image.Format.RGB8 - Image.Format.RGBA8 - Image.Format.Luminance8 - Image.Format.Luminance8Alpha8 - Image.Format.DXT1 - Image.Format.DXT1A - Image.Format.DXT3 - Image.Format.DXT5

      For all other formats, no conversion is performed.

      If this option is toggled at runtime, textures must be reloaded for the change to take effect.

      Parameters:
      linearize - If sRGB images undergo sRGB -> linear conversion prior to rendering.
      Throws:
      RendererException - If the GPU hardware does not support sRGB.
      See Also:

    • generateProfilingTasks

      int[] generateProfilingTasks(int numTasks)
      Generates a pool of gpu queries meant to use as profiling tasks.
      Parameters:
      numTasks - the number of task ids to generate
      Returns:
      an array of tasks ids.

    • startProfiling

      void startProfiling(int taskId)
      Starts a time profiling task on the GPU. This will profile all operations called between startProfiling and stopProfiling
      Parameters:
      taskId - the id of the task to start profiling.

    • stopProfiling

      void stopProfiling()
      Will stop the last profiling task started with startProfiling.

    • getProfilingTime

      long getProfilingTime(int taskId)
      Returns the time in nanoseconds elapsed for the task with the given id. Note that the result may not be available right after stopProfiling has been called. You need to check if the result is available with isTaskResultAvailable. Also note that it's guaranteed that the result will be available on next frame. If you use getProfilingTime on the next frame you called stopProfiling, you don't need to check the result availability with isTaskResultAvailable
      Parameters:
      taskId - the id of the task given by startProfiling.
      Returns:
      the time in nanosecond of the profiling task with the given id.

    • isTaskResultAvailable

      boolean isTaskResultAvailable(int taskId)
      Checks if the profiling results are available.
      Parameters:
      taskId - the id of the task provided by startProfiling
      Returns:
      true if the results of the task with the given task id are available.

    • getAlphaToCoverage

      boolean getAlphaToCoverage()
      Gets the alpha to coverage state.
      Returns:
      true if alpha coverage is enabled, otherwise false

    • getDefaultAnisotropicFilter

      int getDefaultAnisotropicFilter()
      Gets the default anisotropic filter level for textures.
      Returns:
      the default filter level

    • getMaxLineWidth

      float getMaxLineWidth()
      Determines the maximum allowed width for lines.
      Returns:
      the maximum width (in pixels)

    • isLinearizeSrgbImages

      boolean isLinearizeSrgbImages()
      Tests whether images with the sRGB flag will be linearized when read by a shader.
      Returns:
      true for linearization, false for no linearization

    • isMainFrameBufferSrgb

      boolean isMainFrameBufferSrgb()
      Tests whether colors rendered to the main framebuffer undergo linear-to-sRGB conversion.
      Returns:
      true for conversion, false for no conversion

    • popDebugGroup

      default void popDebugGroup()

    • pushDebugGroup

      default void pushDebugGroup(String name)