Public Types | Public Member Functions | Protected Attributes

gfxContext Class Reference

This is the main class for doing actual drawing. More...

#include <gfxContext.h>

Collaboration diagram for gfxContext:

List of all members.

Public Types

enum  gfxLineType { gfxLineSolid, gfxLineDashed, gfxLineDotted }
 

Line Properties.

More...
enum  GraphicsLineCap { LINE_CAP_BUTT, LINE_CAP_ROUND, LINE_CAP_SQUARE }
enum  GraphicsLineJoin { LINE_JOIN_MITER, LINE_JOIN_ROUND, LINE_JOIN_BEVEL }
enum  FillRule { FILL_RULE_WINDING, FILL_RULE_EVEN_ODD }
 

Fill Properties.

More...
enum  GraphicsOperator {
  OPERATOR_CLEAR, OPERATOR_SOURCE, OPERATOR_OVER, OPERATOR_IN,
  OPERATOR_OUT, OPERATOR_ATOP, OPERATOR_DEST, OPERATOR_DEST_OVER,
  OPERATOR_DEST_IN, OPERATOR_DEST_OUT, OPERATOR_DEST_ATOP, OPERATOR_XOR,
  OPERATOR_ADD, OPERATOR_SATURATE
}
 

Operators and Rendering control.

More...
enum  AntialiasMode { MODE_ALIASED, MODE_COVERAGE }
 

MODE_ALIASED means that only pixels whose centers are in the drawn area should be modified, and they should be modified to take the value drawn at the pixel center.

More...
enum  { FLAG_SIMPLIFY_OPERATORS = (1 << 0), FLAG_DISABLE_SNAPPING = (1 << 1), FLAG_DESTINED_FOR_SCREEN = (1 << 2) }
 

Flags.

More...

Public Member Functions

nsrefcnt AddRef (void)
nsrefcnt Release (void)
 gfxContext (gfxASurface *surface)
 Initialize this context from a surface.
 ~gfxContext ()
gfxASurfaceOriginalSurface ()
 Return the surface that this gfxContext was created with.
already_AddRefed< gfxASurfaceCurrentSurface (gfxFloat *dx, gfxFloat *dy)
 Return the current transparency group target, if any, along with its device offsets from the top.
already_AddRefed< gfxASurfaceCurrentSurface ()
cairo_tGetCairo ()
 Return the raw cairo_t object.
PRBool HasError ()
 Returns true if the cairo context is in an error state.
void Save ()
 State.
void Restore ()
void Stroke ()
 Paths & Drawing.
void Fill ()
 Fill the current path according to the current settings.
void NewPath ()
 Forgets the current path.
void ClosePath ()
 Closes the path, i.e.
already_AddRefed< gfxPathCopyPath () const
 Copies the current path and returns the copy.
void AppendPath (gfxPath *path)
 Appends the given path to the current path.
void MoveTo (const gfxPoint &pt)
 Moves the pen to a new point without drawing a line.
void NewSubPath ()
 Creates a new subpath starting at the current point.
gfxPoint CurrentPoint () const
 Returns the current point in the current path.
void LineTo (const gfxPoint &pt)
 Draws a line from the current point to pt.
void CurveTo (const gfxPoint &pt1, const gfxPoint &pt2, const gfxPoint &pt3)
 Draws a cubic Bézier curve with control points pt1, pt2 and pt3.
void QuadraticCurveTo (const gfxPoint &pt1, const gfxPoint &pt2)
 Draws a quadratic Bézier curve with control points pt1, pt2 and pt3.
void Arc (const gfxPoint &center, gfxFloat radius, gfxFloat angle1, gfxFloat angle2)
 Draws a clockwise arc (i.e.
void NegativeArc (const gfxPoint &center, gfxFloat radius, gfxFloat angle1, gfxFloat angle2)
 Draws a counter-clockwise arc (i.e.
void Line (const gfxPoint &start, const gfxPoint &end)
 Draws a line from start to end.
void Rectangle (const gfxRect &rect, PRBool snapToPixels=0)
 Draws the rectangle given by rect.
void Ellipse (const gfxPoint &center, const gfxSize &dimensions)
 Draw an ellipse at the center corner with the given dimensions.
void Polygon (const gfxPoint *points, PRUint32 numPoints)
 Draw a polygon from the given points.
void RoundedRectangle (const gfxRect &rect, const gfxCornerSizes &corners, PRBool draw_clockwise=1)
void Translate (const gfxPoint &pt)
 Transformation Matrix manipulation.
void Scale (gfxFloat x, gfxFloat y)
 Adds a scale to the current matrix.
void Rotate (gfxFloat angle)
 Adds a rotation around the origin to the current matrix.
void Multiply (const gfxMatrix &other)
 Post-multiplies 'other' onto the current CTM, i.e.
void SetMatrix (const gfxMatrix &matrix)
 Replaces the current transformation matrix with matrix.
void IdentityMatrix ()
 Sets the transformation matrix to the identity matrix.
gfxMatrix CurrentMatrix () const
 Returns the current transformation matrix.
gfxPoint DeviceToUser (const gfxPoint &point) const
 Converts a point from device to user coordinates using the inverse transformation matrix.
gfxSize DeviceToUser (const gfxSize &size) const
 Converts a size from device to user coordinates.
gfxRect DeviceToUser (const gfxRect &rect) const
 Converts a rectangle from device to user coordinates; this has the same effect as using DeviceToUser on both the rectangle's point and size.
gfxPoint UserToDevice (const gfxPoint &point) const
 Converts a point from user to device coordinates using the inverse transformation matrix.
gfxSize UserToDevice (const gfxSize &size) const
 Converts a size from user to device coordinates.
gfxRect UserToDevice (const gfxRect &rect) const
 Converts a rectangle from user to device coordinates.
PRBool UserToDevicePixelSnapped (gfxRect &rect, PRBool ignoreScale=0) const
 Takes the given rect and tries to align it to device pixels.
PRBool UserToDevicePixelSnapped (gfxPoint &pt, PRBool ignoreScale=0) const
 Takes the given point and tries to align it to device pixels.
void PixelSnappedRectangleAndSetPattern (const gfxRect &rect, gfxPattern *pattern)
 Attempts to pixel snap the rectangle, add it to the current path, and to set pattern as the current painting source.
void SetDeviceColor (const gfxRGBA &c)
 Painting sources.
PRBool GetDeviceColor (gfxRGBA &c)
 Gets the current color.
void SetColor (const gfxRGBA &c)
 Set a solid color in the sRGB color space to use for drawing.
void SetSource (gfxASurface *surface, const gfxPoint &offset=gfxPoint(0.0, 0.0))
 Uses a surface for drawing.
void SetPattern (gfxPattern *pattern)
 Uses a pattern for drawing.
already_AddRefed< gfxPatternGetPattern ()
 Get the source pattern (solid color, normal pattern, surface, etc).
void Paint (gfxFloat alpha=1.0)
 Painting.
void Mask (gfxPattern *pattern)
 Painting with a Mask.
void Mask (gfxASurface *surface, const gfxPoint &offset=gfxPoint(0.0, 0.0))
 Shorthand for creating a pattern and calling the pattern-taking variant of Mask.
void DrawSurface (gfxASurface *surface, const gfxSize &size)
 Shortcuts.
void SetDash (gfxLineType ltype)
void SetDash (gfxFloat *dashes, int ndash, gfxFloat offset)
void SetLineWidth (gfxFloat width)
 Sets the line width that's used for line drawing.
gfxFloat CurrentLineWidth () const
 Returns the currently set line width.
void SetLineCap (GraphicsLineCap cap)
 Sets the line caps, i.e.
GraphicsLineCap CurrentLineCap () const
void SetLineJoin (GraphicsLineJoin join)
 Sets the line join, i.e.
GraphicsLineJoin CurrentLineJoin () const
void SetMiterLimit (gfxFloat limit)
gfxFloat CurrentMiterLimit () const
void SetFillRule (FillRule rule)
FillRule CurrentFillRule () const
void SetOperator (GraphicsOperator op)
 Sets the operator used for all further drawing.
GraphicsOperator CurrentOperator () const
void SetAntialiasMode (AntialiasMode mode)
AntialiasMode CurrentAntialiasMode () const
void Clip ()
 Clipping.
void ResetClip ()
 Undoes any clipping.
void Clip (const gfxRect &rect)
 Helper functions that will create a rect path and call Clip().
void UpdateSurfaceClip ()
 This will ensure that the surface actually has its clip set.
gfxRect GetClipExtents ()
 This will return the current bounds of the clip region in user space.
void PushGroup (gfxASurface::gfxContentType content=gfxASurface::CONTENT_COLOR)
 Groups.
already_AddRefed< gfxPatternPopGroup ()
void PopGroupToSource ()
PRBool PointInFill (const gfxPoint &pt)
 Hit Testing - check if given point is in the current path.
PRBool PointInStroke (const gfxPoint &pt)
gfxRect GetUserPathExtent ()
 Extents - returns user space extent of current path.
gfxRect GetUserFillExtent ()
gfxRect GetUserStrokeExtent ()
already_AddRefed
< gfxFlattenedPath
GetFlattenedPath ()
 Obtaining a "flattened" path - path converted to all line segments.
void SetFlag (PRInt32 aFlag)
void ClearFlag (PRInt32 aFlag)
PRInt32 GetFlags () const

Protected Attributes

nsAutoRefCnt mRefCnt

Detailed Description

This is the main class for doing actual drawing.

It is initialized using a surface and can be drawn on. It manages various state information like a current transformation matrix (CTM), a current path, current color, etc.

All drawing happens by creating a path and then stroking or filling it. The functions like Rectangle and Arc do not do any drawing themselves. When a path is drawn (stroked or filled), it is filled/stroked with a pattern set by SetPattern, SetColor or SetSource.

Note that the gfxContext takes coordinates in device pixels, as opposed to app units.


Member Enumeration Documentation

anonymous enum

Flags.

Enumerator:
FLAG_SIMPLIFY_OPERATORS 
FLAG_DISABLE_SNAPPING 

When this flag is set, snapping to device pixels is disabled.

It simply never does anything.

FLAG_DESTINED_FOR_SCREEN 

When this flag is set, rendering through this context is destined to be (eventually) drawn on the screen.

It can be useful to know this, for example so that windowed plugins are not unnecessarily rendered (since they will already appear on the screen, thanks to their windows).

MODE_ALIASED means that only pixels whose centers are in the drawn area should be modified, and they should be modified to take the value drawn at the pixel center.

Enumerator:
MODE_ALIASED 
MODE_COVERAGE 

Fill Properties.

Enumerator:
FILL_RULE_WINDING 
FILL_RULE_EVEN_ODD 

Line Properties.

Enumerator:
gfxLineSolid 
gfxLineDashed 
gfxLineDotted 
Enumerator:
LINE_CAP_BUTT 
LINE_CAP_ROUND 
LINE_CAP_SQUARE 
Enumerator:
LINE_JOIN_MITER 
LINE_JOIN_ROUND 
LINE_JOIN_BEVEL 

Operators and Rendering control.

Enumerator:
OPERATOR_CLEAR 
OPERATOR_SOURCE 
OPERATOR_OVER 
OPERATOR_IN 
OPERATOR_OUT 
OPERATOR_ATOP 
OPERATOR_DEST 
OPERATOR_DEST_OVER 
OPERATOR_DEST_IN 
OPERATOR_DEST_OUT 
OPERATOR_DEST_ATOP 
OPERATOR_XOR 
OPERATOR_ADD 
OPERATOR_SATURATE 

Constructor & Destructor Documentation

gfxContext::gfxContext ( gfxASurface surface  ) 

Initialize this context from a surface.

gfxContext::~gfxContext (  ) 

Member Function Documentation

nsrefcnt gfxContext::AddRef ( void   )  [inline]
void gfxContext::AppendPath ( gfxPath path  ) 

Appends the given path to the current path.

void gfxContext::Arc ( const gfxPoint center,
gfxFloat  radius,
gfxFloat  angle1,
gfxFloat  angle2 
)

Draws a clockwise arc (i.e.

a circle segment).

Parameters:
center The center of the circle
radius The radius of the circle
angle1 Starting angle for the segment
angle2 Ending angle
void gfxContext::ClearFlag ( PRInt32  aFlag  )  [inline]
void gfxContext::Clip (  ) 

Clipping.

Clips all further drawing to the current path. This does not consume the current path.

void gfxContext::Clip ( const gfxRect rect  ) 

Helper functions that will create a rect path and call Clip().

Any current path will be destroyed by these functions!

void gfxContext::ClosePath (  ) 

Closes the path, i.e.

connects the last drawn point to the first one.

Filling a path will implicitly close it.

already_AddRefed<gfxPath> gfxContext::CopyPath (  )  const

Copies the current path and returns the copy.

AntialiasMode gfxContext::CurrentAntialiasMode (  )  const
FillRule gfxContext::CurrentFillRule (  )  const
GraphicsLineCap gfxContext::CurrentLineCap (  )  const
GraphicsLineJoin gfxContext::CurrentLineJoin (  )  const
gfxFloat gfxContext::CurrentLineWidth (  )  const

Returns the currently set line width.

See also:
SetLineWidth
gfxMatrix gfxContext::CurrentMatrix (  )  const

Returns the current transformation matrix.

gfxFloat gfxContext::CurrentMiterLimit (  )  const
GraphicsOperator gfxContext::CurrentOperator (  )  const
gfxPoint gfxContext::CurrentPoint (  )  const

Returns the current point in the current path.

already_AddRefed<gfxASurface> gfxContext::CurrentSurface ( gfxFloat dx,
gfxFloat dy 
)

Return the current transparency group target, if any, along with its device offsets from the top.

If no group is active, returns the surface the gfxContext was created with, and 0,0 in dx,dy.

already_AddRefed<gfxASurface> gfxContext::CurrentSurface (  )  [inline]
void gfxContext::CurveTo ( const gfxPoint pt1,
const gfxPoint pt2,
const gfxPoint pt3 
)

Draws a cubic Bézier curve with control points pt1, pt2 and pt3.

gfxPoint gfxContext::DeviceToUser ( const gfxPoint point  )  const

Converts a point from device to user coordinates using the inverse transformation matrix.

gfxSize gfxContext::DeviceToUser ( const gfxSize size  )  const

Converts a size from device to user coordinates.

This does not apply translation components of the matrix.

gfxRect gfxContext::DeviceToUser ( const gfxRect rect  )  const

Converts a rectangle from device to user coordinates; this has the same effect as using DeviceToUser on both the rectangle's point and size.

void gfxContext::DrawSurface ( gfxASurface surface,
const gfxSize size 
)

Shortcuts.

Creates a new path with a rectangle from 0,0 to size.w,size.h and calls cairo_fill.

void gfxContext::Ellipse ( const gfxPoint center,
const gfxSize dimensions 
)

Draw an ellipse at the center corner with the given dimensions.

It extends dimensions.width / 2.0 in the horizontal direction from the center, and dimensions.height / 2.0 in the vertical direction.

void gfxContext::Fill (  ) 

Fill the current path according to the current settings.

Does not consume the current path.

cairo_t* gfxContext::GetCairo (  )  [inline]

Return the raw cairo_t object.

XXX this should go away at some point.

gfxRect gfxContext::GetClipExtents (  ) 

This will return the current bounds of the clip region in user space.

PRBool gfxContext::GetDeviceColor ( gfxRGBA c  ) 

Gets the current color.

It's returned in the device color space. returns PR_FALSE if there is something other than a color set as the current source (pattern, surface, etc)

PRInt32 gfxContext::GetFlags (  )  const [inline]
already_AddRefed<gfxFlattenedPath> gfxContext::GetFlattenedPath (  ) 

Obtaining a "flattened" path - path converted to all line segments.

already_AddRefed<gfxPattern> gfxContext::GetPattern (  ) 

Get the source pattern (solid color, normal pattern, surface, etc).

gfxRect gfxContext::GetUserFillExtent (  ) 
gfxRect gfxContext::GetUserPathExtent (  ) 

Extents - returns user space extent of current path.

gfxRect gfxContext::GetUserStrokeExtent (  ) 
PRBool gfxContext::HasError (  ) 

Returns true if the cairo context is in an error state.

void gfxContext::IdentityMatrix (  ) 

Sets the transformation matrix to the identity matrix.

void gfxContext::Line ( const gfxPoint start,
const gfxPoint end 
)

Draws a line from start to end.

void gfxContext::LineTo ( const gfxPoint pt  ) 

Draws a line from the current point to pt.

See also:
MoveTo
void gfxContext::Mask ( gfxPattern pattern  ) 

Painting with a Mask.

Like Paint, except that it only draws the source where pattern is non-transparent.

void gfxContext::Mask ( gfxASurface surface,
const gfxPoint offset = gfxPoint(0.0, 0.0) 
)

Shorthand for creating a pattern and calling the pattern-taking variant of Mask.

void gfxContext::MoveTo ( const gfxPoint pt  ) 

Moves the pen to a new point without drawing a line.

void gfxContext::Multiply ( const gfxMatrix other  ) 

Post-multiplies 'other' onto the current CTM, i.e.

this matrix's transformation will take place before the previously set transformations.

void gfxContext::NegativeArc ( const gfxPoint center,
gfxFloat  radius,
gfxFloat  angle1,
gfxFloat  angle2 
)

Draws a counter-clockwise arc (i.e.

a circle segment).

Parameters:
center The center of the circle
radius The radius of the circle
angle1 Starting angle for the segment
angle2 Ending angle
void gfxContext::NewPath (  ) 

Forgets the current path.

void gfxContext::NewSubPath (  ) 

Creates a new subpath starting at the current point.

Equivalent to MoveTo(CurrentPoint()).

gfxASurface* gfxContext::OriginalSurface (  ) 

Return the surface that this gfxContext was created with.

void gfxContext::Paint ( gfxFloat  alpha = 1.0  ) 

Painting.

Paints the current source surface/pattern everywhere in the current clip region.

void gfxContext::PixelSnappedRectangleAndSetPattern ( const gfxRect rect,
gfxPattern pattern 
)

Attempts to pixel snap the rectangle, add it to the current path, and to set pattern as the current painting source.

This should be used for drawing filled pixel-snapped rectangles (like images), because the CTM at the time of the SetPattern call needs to have a snapped translation, or you get smeared images.

PRBool gfxContext::PointInFill ( const gfxPoint pt  ) 

Hit Testing - check if given point is in the current path.

PRBool gfxContext::PointInStroke ( const gfxPoint pt  ) 
void gfxContext::Polygon ( const gfxPoint points,
PRUint32  numPoints 
)

Draw a polygon from the given points.

already_AddRefed<gfxPattern> gfxContext::PopGroup (  ) 
void gfxContext::PopGroupToSource (  ) 
void gfxContext::PushGroup ( gfxASurface::gfxContentType  content = gfxASurface::CONTENT_COLOR  ) 

Groups.

void gfxContext::QuadraticCurveTo ( const gfxPoint pt1,
const gfxPoint pt2 
)

Draws a quadratic Bézier curve with control points pt1, pt2 and pt3.

void gfxContext::Rectangle ( const gfxRect rect,
PRBool  snapToPixels = 0 
)

Draws the rectangle given by rect.

Parameters:
snapToPixels ?
nsrefcnt gfxContext::Release ( void   )  [inline]
void gfxContext::ResetClip (  ) 

Undoes any clipping.

Further drawings will only be restricted by the surface dimensions.

void gfxContext::Restore (  ) 
void gfxContext::Rotate ( gfxFloat  angle  ) 

Adds a rotation around the origin to the current matrix.

This rotation takes place before the previously set transformations.

Parameters:
angle The angle in radians.
void gfxContext::RoundedRectangle ( const gfxRect rect,
const gfxCornerSizes corners,
PRBool  draw_clockwise = 1 
)
void gfxContext::Save (  ) 

State.

void gfxContext::Scale ( gfxFloat  x,
gfxFloat  y 
)

Adds a scale to the current matrix.

This scaling takes place before the previously set transformations.

void gfxContext::SetAntialiasMode ( AntialiasMode  mode  ) 
void gfxContext::SetColor ( const gfxRGBA c  ) 

Set a solid color in the sRGB color space to use for drawing.

If CMS is not enabled, the color is treated as a device-space color and this call is identical to SetDeviceColor().

void gfxContext::SetDash ( gfxLineType  ltype  ) 
void gfxContext::SetDash ( gfxFloat dashes,
int  ndash,
gfxFloat  offset 
)
void gfxContext::SetDeviceColor ( const gfxRGBA c  ) 

Painting sources.

Set a solid color to use for drawing. This color is in the device color space and is not transformed.

void gfxContext::SetFillRule ( FillRule  rule  ) 
void gfxContext::SetFlag ( PRInt32  aFlag  )  [inline]
void gfxContext::SetLineCap ( GraphicsLineCap  cap  ) 

Sets the line caps, i.e.

how line endings are drawn.

void gfxContext::SetLineJoin ( GraphicsLineJoin  join  ) 

Sets the line join, i.e.

how the connection between two lines is drawn.

void gfxContext::SetLineWidth ( gfxFloat  width  ) 

Sets the line width that's used for line drawing.

void gfxContext::SetMatrix ( const gfxMatrix matrix  ) 

Replaces the current transformation matrix with matrix.

void gfxContext::SetMiterLimit ( gfxFloat  limit  ) 
void gfxContext::SetOperator ( GraphicsOperator  op  ) 

Sets the operator used for all further drawing.

The operator affects how drawing something will modify the destination. For example, the OVER operator will do alpha blending of source and destination, while SOURCE will replace the destination with the source.

Note that if the flag FLAG_SIMPLIFY_OPERATORS is set on this gfxContext, the actual operator set might change for optimization purposes. Check the comments below around that flag.

void gfxContext::SetPattern ( gfxPattern pattern  ) 

Uses a pattern for drawing.

void gfxContext::SetSource ( gfxASurface surface,
const gfxPoint offset = gfxPoint(0.0, 0.0) 
)

Uses a surface for drawing.

This is a shorthand for creating a pattern and setting it.

Parameters:
offset from the source surface, to use only part of it. May need to make it negative.
void gfxContext::Stroke (  ) 

Paths & Drawing.

Stroke the current path using the current settings (such as line width and color). A path is set up using functions such as Line, Rectangle and Arc.

Does not consume the current path.

void gfxContext::Translate ( const gfxPoint pt  ) 

Transformation Matrix manipulation.

Adds a translation to the current matrix. This translation takes place before the previously set transformations.

void gfxContext::UpdateSurfaceClip (  ) 

This will ensure that the surface actually has its clip set.

Useful if you are doing native drawing.

gfxPoint gfxContext::UserToDevice ( const gfxPoint point  )  const

Converts a point from user to device coordinates using the inverse transformation matrix.

gfxRect gfxContext::UserToDevice ( const gfxRect rect  )  const

Converts a rectangle from user to device coordinates.

The resulting rectangle is the minimum device-space rectangle that encloses the user-space rectangle given.

gfxSize gfxContext::UserToDevice ( const gfxSize size  )  const

Converts a size from user to device coordinates.

This does not apply translation components of the matrix.

PRBool gfxContext::UserToDevicePixelSnapped ( gfxPoint pt,
PRBool  ignoreScale = 0 
) const

Takes the given point and tries to align it to device pixels.

If this succeeds, the method will return PR_TRUE, and the point will be in device coordinates (already transformed by the CTM). If it fails, the method will return PR_FALSE, and the point will not be changed.

If ignoreScale is PR_TRUE, then snapping will take place even if the CTM has a scale applied. Snapping never takes place if there is a rotation in the CTM.

PRBool gfxContext::UserToDevicePixelSnapped ( gfxRect rect,
PRBool  ignoreScale = 0 
) const

Takes the given rect and tries to align it to device pixels.

If this succeeds, the method will return PR_TRUE, and the rect will be in device coordinates (already transformed by the CTM). If it fails, the method will return PR_FALSE, and the rect will not be changed.

If ignoreScale is PR_TRUE, then snapping will take place even if the CTM has a scale applied. Snapping never takes place if there is a rotation in the CTM.


Member Data Documentation

nsAutoRefCnt gfxContext::mRefCnt [protected]

The documentation for this class was generated from the following file: