Package ej.microui.display

Class GraphicsContext

  • public class GraphicsContext
extends Object
    A GraphicsContext provides access to a modifiable pixel buffer.

    For example, a graphics context can be used to read or write the pixels of the Display or of a BufferedImage.

    Painting classes such as Painter provide utility methods to draw specific shapes and objects using a graphics context.

    Colors are interpreted as 24-bit RGB colors. If the display or image associated with the graphics context does not support such color depth, its implementation is in charge of mapping the desired colors to the most appropriate supported colors.

    A graphics context defines a translation vector in order to change the position of subsequent drawings.

    It also defines a clipping rectangle which restricts the pixels that will be modified by subsequent drawings. Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed. The position of this clipping area is relative to the origin of this graphics context, regardless of the value of the translation vector.

    A graphics context uses the following coordinate system:

    • its origin is the top-left corner of the top-left pixel of the destination.
    • its x axis is positive towards the right.
    • its y axis is positive towards the bottom.

    • Constructor Summary

      Constructors 
      Constructor Description
      GraphicsContext()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int checkDrawingLogFlags()
      Throws an exception if the error flag is currently set.
      void disableEllipsis()
      Disables ellipsis.
      void enableEllipsis​(int width)
      Enables ellipsis when drawing characters.
      static int getAlpha​(int opacityPercent)
      Returns the alpha level for the given opacity percentage.
      int getAndClearDrawingLogFlags()
      Gets and clears the drawing log flags from a graphics context.
      int getBackgroundColor()
      Returns the background color of this graphics context.
      int getClipHeight()
      Returns the height of the clipping area of this graphics context.
      int getClipWidth()
      Returns the width of the clipping area of this graphics context.
      int getClipX()
      Returns the x coordinate of the clipping area of this graphics context.
      int getClipY()
      Returns the y coordinate of the clipping area of this graphics context.
      int getColor()
      Returns the color of this graphics context.
      int getEllipsisWidth()
      Returns the width limit before applying the ellipsis.
      int getHeight()
      Returns the height of this graphics context.
      int getTranslationX()
      Returns the x coordinate of the translation vector of this graphics context.
      int getTranslationY()
      Returns the y coordinate of the translation vector of this graphics context.
      int getWidth()
      Returns the width of this graphics context.
      boolean hasBackgroundColor()
      Returns whether this graphics context has a background color.
      void intersectClip​(int x, int y, int width, int height)
      Combines the given clipping rectangle with the clipping area of this graphics context.
      void notifyDrawingRegion()
      Notifies that the current clip will be considered as a completely repainted region by subsequent drawings.
      int readPixel​(int x, int y)
      Returns the color of a pixel of this graphics context.
      void readPixels​(int[] array, int offset, int scanLength, int x, int y, int width, int height)
      Retrieves the color of the pixels of a region of this graphics context.
      void removeBackgroundColor()
      Removes the background color of this graphics context.
      void reset()
      Resets this graphics context to its initial configuration.
      void resetClip()
      Resets the clipping area of this graphics context to its entire bounds.
      void resetTranslation()
      Resets the translation vector of this graphics context to the (0,0) vector.
      void setBackgroundColor​(int color)
      Sets the background color of this graphics context.
      void setClip​(int x, int y, int width, int height)
      Sets the clipping area of this graphics context to the given rectangle.
      void setColor​(int color)
      Sets the color of this graphics context.
      void setTranslation​(int x, int y)
      Sets the translation vector of this graphics context to the (x,y) vector.
      void translate​(int x, int y)
      Adds a given translation vector to the translation vector of this graphics context.

    • Field Detail

      • OPAQUE

        public static final int OPAQUE
        Maximum opacity.

        The opacity level (called alpha) is used by some Painter drawing methods to specify the drawing global opacity. When the opacity is maximal, the drawing is fully opaque. When opacity is a value between TRANSPARENT and OPAQUE, the drawing is merging the foreground color with the destination pixel color or with the global background color. When the opacity is TRANSPARENT, the drawing is fully transparent (nothing is drawn).

        The opacity is an unsigned byte value between 0 (fully transparent) and 255 (fully opaque). All other values are meaningless.

        The method getAlpha(int) allows to convert an opacity expressed in percentage (0% means fully transparent and 100% fully opaque) in an opacity understandable by the Painter drawing methods.

        Since:
        2.0
        See Also:
        getAlpha(int), Painter.drawImage(GraphicsContext, Image, int, int, int), Constant Field Values

      • DRAWING_SUCCESS

        public static final int DRAWING_SUCCESS
        Value used when no incident occurred.
        See Also:
        Constant Field Values

      • DRAWING_LOG_ERROR

        public static final int DRAWING_LOG_ERROR
        Flag stating that an error occurred during a drawing. This flag will cause an exception to be thrown when checking the flags in the application. No exception will be thrown if this flag is not set, although other flags will keep their state and be readable in the application. This flag is to be combined with other flags describing the error.
        See Also:
        Constant Field Values

      • DRAWING_LOG_NOT_IMPLEMENTED

        public static final int DRAWING_LOG_NOT_IMPLEMENTED
        Flag stating that a drawing function is lacking an implementation. This flag is typically set when the format of the graphics context is not supported by the implementation.
        See Also:
        Constant Field Values

      • DRAWING_LOG_FORBIDDEN

        public static final int DRAWING_LOG_FORBIDDEN
        Flag stating that a function was called in a context that does not allow that operation. This flag is typically set when a drawing function has been disabled for a specific format, like a vector drawing function called on a raster-only graphics context.
        See Also:
        Constant Field Values

      • DRAWING_LOG_OUT_OF_MEMORY

        public static final int DRAWING_LOG_OUT_OF_MEMORY
        Flag stating that the system ran out of memory while attempting to perform a drawing.
        See Also:
        Constant Field Values

      • DRAWING_LOG_CLIP_MODIFIED

        public static final int DRAWING_LOG_CLIP_MODIFIED
        Flag stating that the clip area of a graphics context was modified by the low-level side. This flag merely warns the user that the clip values returned by getClipX(), getClipY(), getClipWidth() and getClipHeight()` may not be identical to the clip values used in the low-level side, notably if the modified low-level values were not properly restored. It is meant to be used as a debugging hint if a drawing seems incorrect.
        See Also:
        Constant Field Values

      • DRAWING_LOG_MISSING_CHARACTER

        public static final int DRAWING_LOG_MISSING_CHARACTER
        Flag stating that an undefined character was drawn. This happens when drawing a string that contains a character that is not included in the font used.
        See Also:
        Constant Field Values

      • DRAWING_LOG_LIBRARY_INCIDENT

        public static final int DRAWING_LOG_LIBRARY_INCIDENT
        Flag describing incidents occurring in a drawing library. Refer to the MicroUI implementation in the VEE port for more information about this incident.
        See Also:
        Constant Field Values

      • DRAWING_LOG_UNKNOWN_INCIDENT

        public static final int DRAWING_LOG_UNKNOWN_INCIDENT
        Flag describing incidents that do not match other values.
        See Also:
        Constant Field Values

    • Constructor Detail

      • GraphicsContext

        public GraphicsContext()

    • Method Detail

      • getAlpha

        public static int getAlpha​(int opacityPercent)
        Returns the alpha level for the given opacity percentage.

        The returned value may be used in some painting methods such as Painter.drawImage(GraphicsContext, Image, int, int, int).

        Parameters:
        opacityPercent - the opacity, in percents.
        Returns:
        the alpha level.
        Since:
        2.0

      • getWidth

        public int getWidth()
        Returns the width of this graphics context.
        Returns:
        the width of this graphics context, in pixels.

      • getHeight

        public int getHeight()
        Returns the height of this graphics context.
        Returns:
        the height of this graphics context, in pixels.

      • reset

        public void reset()
        Resets this graphics context to its initial configuration.

        This methods

        • resets both the translation and the clip to their initial state,
        • sets the color to Colors.BLACK,
        • removes the background color,
        • resets the ellipsis.

      • resetTranslation

        public void resetTranslation()
        Resets the translation vector of this graphics context to the (0,0) vector.

      • setTranslation

        public void setTranslation​(int x,
                           int y)
        Sets the translation vector of this graphics context to the (x,y) vector.
        Parameters:
        x - the x coordinate of the translation vector, in pixels.
        y - the y coordinate of the translation vector, in pixels.

      • translate

        public void translate​(int x,
                      int y)
        Adds a given translation vector to the translation vector of this graphics context.

        The new translation vector is equal to the sum of the given translation vector and the current translation vector.

        Parameters:
        x - the x coordinate of the translation vector to add, in pixels.
        y - the y coordinate of the translation vector to add, in pixels.

      • getTranslationX

        public int getTranslationX()
        Returns the x coordinate of the translation vector of this graphics context.
        Returns:
        the x coordinate of the translation vector of this graphics context, in pixels.

      • getTranslationY

        public int getTranslationY()
        Returns the y coordinate of the translation vector of this graphics context.
        Returns:
        the y coordinate of the translation vector of this graphics context, in pixels.

      • setColor

        public void setColor​(int color)
        Sets the color of this graphics context.

        The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

        Parameters:
        color - the color to set.

      • setBackgroundColor

        public void setBackgroundColor​(int color)
        Sets the background color of this graphics context.

        The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

        The background color is only used by some drawing methods. If the background color is not set, these algorithms have to read the destination pixel color and blend it with the desired color.

        The background color is irrelevant for black and white displays.

        Parameters:
        color - the color to set.

      • removeBackgroundColor

        public void removeBackgroundColor()
        Removes the background color of this graphics context.

      • getColor

        public int getColor()
        Returns the color of this graphics context.

        The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

        Returns:
        the color of this graphics context.

      • getBackgroundColor

        public int getBackgroundColor()
        Returns the background color of this graphics context.

        The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

        Returns:
        the background color of this graphics context.

      • hasBackgroundColor

        public boolean hasBackgroundColor()
        Returns whether this graphics context has a background color.
        Returns:
        true if a background color has been set, false otherwise.

      • intersectClip

        public void intersectClip​(int x,
                          int y,
                          int width,
                          int height)
        Combines the given clipping rectangle with the clipping area of this graphics context.

        This method sets the clipping area to be the intersection of the given rectangle with the current clipping area.

        Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.

        Given clip origin is translated according current graphics context translation.

        Parameters:
        x - the x coordinate of the rectangle, in pixels.
        y - the y coordinate of the rectangle, in pixels.
        width - the width of the rectangle, in pixels.
        height - the height of the rectangle, in pixels.

      • setClip

        public void setClip​(int x,
                    int y,
                    int width,
                    int height)
        Sets the clipping area of this graphics context to the given rectangle.

        Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.

        Given clip origin is translated according current graphics context translation.

        Parameters:
        x - the x coordinate of the rectangle, in pixels.
        y - the y coordinate of the rectangle, in pixels.
        width - the width of the rectangle, in pixels.
        height - the height of the rectangle, in pixels.

      • resetClip

        public void resetClip()
        Resets the clipping area of this graphics context to its entire bounds.

        The current graphics context translation is not taken into account.

        This is equivalent to calling gc.setClip(-gc.getTranslationX(), -gc.getTranslationY(), gc.getWidth(), gc.getHeight()).

      • getClipX

        public int getClipX()
        Returns the x coordinate of the clipping area of this graphics context.

        Returned clip origin is translated according current graphics context translation.

        Returns:
        the x coordinate of the clipping area of this graphics context, in pixels.

      • getClipY

        public int getClipY()
        Returns the y coordinate of the clipping area of this graphics context.

        Returned clip origin is translated according current graphics context translation.

        Returns:
        the y coordinate of the clipping area of this graphics context, in pixels.

      • getClipWidth

        public int getClipWidth()
        Returns the width of the clipping area of this graphics context.
        Returns:
        the width of the clipping area of this graphics context, in pixels.

      • getClipHeight

        public int getClipHeight()
        Returns the height of the clipping area of this graphics context.
        Returns:
        the height of the clipping area of this graphics context, in pixels.

      • notifyDrawingRegion

        public void notifyDrawingRegion()
        Notifies that the current clip will be considered as a completely repainted region by subsequent drawings. A clip is already considered as a fully repainted region before each drawing. This method allows a larger region to be notified even if the first drawing in this region uses a smaller clip. This may avoid unnecessary restoration of the contents of this region (in whole or in part). This call has no effect when the graphics context does not target the display.

      • enableEllipsis

        public void enableEllipsis​(int width)
        Enables ellipsis when drawing characters.

        When ellipsis is enabled, characters are truncated if their rendering width is higher than the specified width limit. In this case, the last visible character is replaced by the ellipsis character (three dots).

        To configure ellipsis using the clipping area as text limit, the given width should be equal to getClipX() + getClipWidth() - x, where x is the x coordinate of the drawing.

        The ellipsis is only used by the methods drawing characters.

        Parameters:
        width - the width limit, in pixels.
        Throws:
        IllegalArgumentException - if width is negative or zero.

      • getEllipsisWidth

        public int getEllipsisWidth()
        Returns the width limit before applying the ellipsis.

        If ellipsis is disabled, this method returns zero.

        Returns:
        the width limit, in pixels.

      • disableEllipsis

        public void disableEllipsis()
        Disables ellipsis.

      • readPixel

        public int readPixel​(int x,
                     int y)
        Returns the color of a pixel of this graphics context.

        For more information on the format of the color value returned by this method, refer to the first paragraphs of the centralized pixel reading documentation.

        Given position is translated according to the current graphics context translation.

        Parameters:
        x - the x coordinate of the pixel.
        y - the y coordinate of the pixel.
        Returns:
        the color of the pixel, in ARGB format.
        Throws:
        IllegalArgumentException - if the given pixel coordinates are out of the bounds of this graphics context.
        MicroUIException - if this graphics context is associated with a resource which has been closed.

      • readPixels

        public void readPixels​(int[] array,
                       int offset,
                       int scanLength,
                       int x,
                       int y,
                       int width,
                       int height)
        Retrieves the color of the pixels of a region of this graphics context.

        Each pixel color is stored in 32-bit ARGB format, where the high-order byte contains the alpha channel and the remaining bytes contain the red, green and blue channels, respectively. This is relevant regardless of the format in which the pixels are stored internally. The alpha channel specifies the opacity of the pixel, ranging between TRANSPARENT and OPAQUE.

        The retrieved colors are not guaranteed to be identical to the colors from the original source. Indeed, color values may be resampled to reflect the display capabilities of the device. For example, red, green and blue pixels may all be represented by the same color value on a grayscale device.

        On displays which do not support alpha blending, the alpha component will be equal to OPAQUE for opaque pixels and TRANSPARENT for every other pixel. On displays that support alpha blending, alpha channel values may be resampled to reflect the number of levels of opacity supported by the display.

        The data is stored in the given int array, which should be big enough to hold the color of all the pixels of the region.

        The scan length specifies the relative offset within the array between two pixels of consecutive rows. In order to prevent rows of stored pixels from overlapping, the absolute value of the scan length should be greater than or equal to the width of the region. Negative values of scan length are allowed if the order of rows is inverted in the array.

        If an exception occurs during this method, the contents of the given array will remain unchanged.

        Given position is translated according to the current graphics context translation.

        Parameters:
        array - the array in which the pixel data should be stored.
        offset - the index of the array at which the first pixel color should be stored.
        scanLength - the relative offset in the array between two corresponding pixels in consecutive rows.
        x - the x-coordinate of the top-left pixel of the region.
        y - the y-coordinate of the top-left pixel of the region.
        width - the width of the region.
        height - the height of the region.
        Throws:
        ArrayIndexOutOfBoundsException - if the array is not big enough to hold the color of all the pixels of the region.
        IllegalArgumentException - if a part of the region is out of the bounds of this graphics context.
        IllegalArgumentException - if the absolute value of scanLength is lower than width.
        MicroUIException - if this graphics context is associated with a resource which has been closed.

      • getAndClearDrawingLogFlags

        public int getAndClearDrawingLogFlags()
        Gets and clears the drawing log flags from a graphics context. The flags are reset to their success value after retrieving their value. This method is identical to checkDrawingLogFlags(), except it does not throw an exception if the error flag has been set. Both methods are meant to help investigate drawing errors.
        Returns:
        the drawing log flags

      • checkDrawingLogFlags

        public int checkDrawingLogFlags()
        Throws an exception if the error flag is currently set. The drawing log flags are reset to their success value after retrieving their value. This method is identical to getAndClearDrawingLogFlags(), except it throws an exception if the error flag has been set. Both methods are meant to help investigate drawing errors.
        Returns:
        the drawing log flags
        Throws:
        MicroUIException - if the error flag was set
        See Also:
        Error flag